Octop Self-Hosted AI Assistant Deployment SOP

Tencent Cloud released Octop 1.0 GA on 2026-09-17, an open-source, self-hosted, multi-user AI assistant (source: official WeChat account; GitHub TencentCloud/Octop, Python, MIT, 3,198 stars measured on release day). It packs a web console, a CLI, IM channels, and cron automation into one process; all state lives under ~/.octop/, with SQLite as the default control-plane database (PostgreSQL optional). This is a no-hype, hands-on SOP that walks the deployment steps from "should I self-host at all" to a pre-launch checklist. Every install command, config path, and default port is quoted verbatim from the official README. For the backstory of this GA release, see the Octop 1.0 GA launch hotspot.

Should you self-host

Start with a decision, then touch the keyboard. Octop fits three profiles. Profile one: data-sensitive users who want chats, workspaces, and credentials on their own machine, local-first and offline-capable, with PII redacted before it leaves. Profile two: families sharing one admin account while each member keeps an independent memory, workspace, and expert config. Profile three: solo founders or small teams willing to run a server in exchange for control, offline access, and auditability. It is not for people who just want AI without ops; if port forwarding already annoys you, a cloud assistant is the calmer choice.

The only test that matters: are you willing to pay the ops cost for data in your own hands? If yes, keep reading. If no, close this and use a SaaS. If you are still torn between self-hosting and cloud, read the self-hosted AI assistant comparison review first and price the cost. Remember Octop is single-process: the web console, CLI, IM channels, and cron all run in one process, and on restart it rebuilds all state from the control-plane database. That is convenient, but it also means the availability of this machine is the availability of the service.

Install path choice (table 1: method comparison)

README offers four install methods for different audiences and hardware. Verdict first: for long-running, multi-user production, go straight to Docker Compose; for a quick local try, the one-line script on macOS or Linux is the least friction; Windows users take the PowerShell script; domestic users who hate the command line get the smoothest path from the Tencent Cloud Lighthouse and CVM marketplace images that went live on GA day (source: official WeChat account, one-command deploy).

On macOS and Linux the recommended installer is one line, copied verbatim from the README:

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash

Windows uses the PowerShell one-liner:

irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iex

For production, use Docker Compose, also from the README:

docker compose -f docker/docker-compose.yml up -d

After install on macOS or Linux, open a new terminal or reload the shell so ~/.octop/bin enters the PATH:

source ~/.zshrc   # Zsh
# or
source ~/.bashrc  # Bash

README also ships optional extras such as browser automation (Playwright Chromium) and the Feishu channel, enabled with a --extras flag; details follow the README scripts notes. On hardware floors, README's wording is "a modern multi-core CPU, a few GB of RAM for the process plus model or embedding caches, enough disk for the database, agent workspaces, and document corpora". It does not pin a core count, so do not run production on a Raspberry Pi.

Initialize: octop init and octop run

The first step after install is init, which builds the database, the JWT secret, and the first admin, all under ~/.octop/:

octop init

README calls this an interactive wizard that creates the SQLite database, JWT secret, and first admin account. Next, start it to bring up the API and web console in the foreground:

# Foreground (API + web console)
octop run

# Custom host / port
octop run --host 0.0.0.0 --port 8088

# Register as a system service (systemd / launchd / Windows service)
octop service start

After start, open http://127.0.0.1:8088. The default port is 8088, written in the README; do not misremember it as something else. With Docker, the first init generates a random admin password written to /data/.octop/credential.txt unless you set OCTOP_DEFAULT_PASSWORD; the interactive octop init or setup wizard asks you to pick a password of at least 8 characters with letters and digits.

Want API docs? README is explicit: /api/docs is off by default and only turns on when you set enable_api_docs to true in config.json. Leaving it off is the right default; do not expose it to the public net just for debugging.

First security hardening

This is where most people crash. The default admin account is admin; the README does not hardcode a default password, third-party reviews report octop, and a Docker first init generates a random password written to credential.txt. Whichever default you get, change it on first login without exception. Exposing admin / octop to the public internet is leaving the door open for scanners. Octop's password policy requires at least 8 characters with both letters and digits; weak or common passwords are rejected and fall back to a random one.

Hardening is more than a password:

• Tool approval and shell guardrails: risky tools and shell commands need explicit approval; guardrail rules are editable under ~/.octop/security/tool_guard/. In production, turn this on so the AI never runs rm -rf on your behalf.
• PII redaction: sensitive data is redacted before it leaves the workspace; this is part of the local-first design, so confirm it is on.
• Surface reduction: if you only use it on your own machine, octop run --host 127.0.0.1 is enough; do not bind 0.0.0.0 and run naked on the public net just for convenience. To expose it, put a reverse proxy with TLS in front; never serve plaintext HTTP to the public.
• Multi-user isolation: the admin creates member accounts with JWT isolation, each having independent memory, workspace, and expert config. Do not share the admin account across the family out of laziness.

Security is a selling point of Octop (local-first and offline, tool approval, shell guardrails, PII redaction), but selling points do not turn themselves on; you have to flip the switches.

Connect models

Octop supports OpenAI-compatible endpoints, DashScope (Qwen), Ollama local models, and other presets; README's wording is "nearly 20 vendors". Two ways to configure: per agent in the web console, or via CLI. First inspect what is supported:

# LLM providers and models
octop models
octop provider list

For Ollama local models: start the service on the Ollama side and point Octop's provider config at its address; the exact field names are not listed line by line in the README, so follow the official docs. OpenAI-compatible endpoints work by filling base_url and key, which makes it easy to plug into any compatible gateway. The key point is per-agent keys with least privilege: do not hand one all-powerful shared key to every agent, because one leak takes down the whole line. README does not spell out each vendor's exact fields, so key and endpoint formats follow the official docs.

Basic model choice: general chat and writing use a general model, code generation uses a code-oriented model, and private data stays local through Ollama without leaving the machine. For wiring Octop into an existing Harness stack, see the Harness tech-stack resource.

Experts, connectors, and IM channels

Octop's differentiation is the expert library and connectors. The expert library is scanned at boot from infra/agents/experts/library/, ships 16 MBTI persona templates, and accepts a custom system prompt; pick an expert or persona per agent so different tasks switch to different "characters". Connectors ride OAuth plus an MCP gateway and cover Tencent Docs, Tencent Cloud OpenAPI, and news hot search, extending the resource boundary outward.

IM channels let Octop work inside group chats. Supported channels and credentials (from README):

Install and list channels via CLI:

# List IM channels
octop channel list

# Install a channel
octop channel install

The most common IM pitfall is the callback config: channels that need a public callback, such as Feishu and WeCom, require you to check the App Secret, callback URL, and egress IP; miss one and you receive nothing. QQ and Discord are simpler, just fill the token. How to write MCP extensions and how to authorize connector OAuth are not given verbatim in the README, so follow the official docs.

Production and operations

For real production, Docker Compose is the shape README explicitly recommends. All data lives under ~/.octop/, which holds config.json (process config), octop.db (SQLite: users, agents, channels, cron), secrets/ (JWT secret and channel tokens), agents/<agent_id>/ (per-agent workspace), security/tool_guard/ (shell allow or deny rules), logs/, venv/, and bin/octop.

Switch to PostgreSQL: set the database section in config.json, or use OCTOP_DATABASE_* environment variables, or fill it in the first-run wizard. Note README is explicit: with PostgreSQL, agent memory reuses the same DSN by default (a per-agent schema); to keep file-based memory, set "memory": { "backend": { "type": "sqlite" } } in the agent config.

Backup and upgrade:

# Export / restore backups
octop backup

# Upgrade: replaces only the wheel or binary; database, workspaces, secrets, config.json preserved
octop update

octop update replaces only the wheel or binary; the database, workspaces, secrets, and config.json under ~/.octop/ are preserved, and the schema migrates automatically on next boot; run octop init only when the wizard prompts for a migration. Before a cross-version upgrade, always octop backup first. The second table lists the high-frequency pitfalls.

Pre-launch checklist

• Changed the default admin password (at least 8 chars, letters plus digits)
• Public exposure behind a TLS reverse proxy, or bound to 127.0.0.1 only
• Tool approval and shell guardrails on (~/.octop/security/tool_guard/)
• PII redaction enabled
• Model keys split per agent with least privilege, no shared all-powerful key
• Database backend chosen (SQLite single-user / PostgreSQL multi-user)
• IM channel callbacks and egress allowlist configured
• First octop backup done, ~/.octop/ archived
• System service registered (octop service start) or Docker auto-start
• octop backup before upgrade, then octop update

FAQ

Q1: Should I self-host Octop at all? A1: Self-host if you are data-sensitive, share with family, or run a solo company and accept server ops; use a cloud assistant if you want AI without maintenance. The only test is whether you will pay the ops cost for data in your own hands.

Q2: What is the minimum hardware? A2: README gives no fixed core count, only "a modern multi-core CPU, a few GB of RAM for the process plus model or embedding caches, enough disk for the database, agent workspaces, and document corpora". The installer builds an isolated Python 3.12+ venv under ~/.octop/ via uv, no system Python required. Do not run production on low-end hardware.

Q3: What are the default credentials, and must I change them? A3: Default admin account is admin; the README does not hardcode a default password, third-party reviews report octop, and Docker init generates a random one in credential.txt. Either way, change it on first login without exception. The policy needs at least 8 characters with both letters and digits, and weak passwords are rejected and fall back to random. Leaving it exposed is an open door.

Q4: Is SQLite enough, and when do I move to PostgreSQL? A4: Single user, low frequency, few writers is fine. When concurrent writes stall or lock, move to PostgreSQL by setting the database section in config.json or OCTOP_DATABASE_*. Note that under PostgreSQL, agent memory reuses the same DSN by default; to keep file-based memory, set it separately in the agent config.

Q5: Does upgrade lose data? A5: No. octop update replaces only the wheel or binary; the database, workspaces, secrets, and config.json under ~/.octop/ are preserved, and the schema migrates on next boot. But before a cross-version upgrade, always octop backup first.

References

• Octop official README (install commands, ports, paths, vendor and channel credentials quoted verbatim): TencentCloud/Octop
• Octop 1.0 GA and Tencent Cloud Lighthouse / CVM marketplace one-command deploy: Tencent Cloud official WeChat account (2026-09-17)
• Harness stack (harness-agent / harness-gateway / harness-memory / harness-browser): README related projects section