How to Install Octop: A Self-Hosted Multi-User, Multi-Agent AI Assistant from Tencent Cloud

If you have a spare Linux machine or NAS and want to run a multi-user, multi-agent AI assistant with your own models and local data, Octop is a practical option. It is an open-source project from Tencent Cloud that takes a local-first approach, unlike the SaaS model of its sibling WorkBuddy, which requires login and credits. This guide covers installation, startup, data directories, configuration, extensions, and development, and highlights the parameters and directories that are easy to miss.

What Do You Need Before Installing Octop?

The most common question is whether you need to install Python first. You do not. The installer uses uv to create an isolated Python 3.12 virtual environment under ~/.octop/, and it does not touch your system Python.

Octop supports macOS, Linux, and Windows. For hardware, the README recommends a modern multi-core CPU, a few GB of RAM for the process and model or embedding cache, and enough disk space for the database, agent workspaces, and document corpus.

One step is easy to miss after installation. The installer adds octop to your PATH at ~/.octop/bin, but your current terminal will not see it immediately. Open a new terminal, or reload your shell configuration manually. For Zsh, run source ~/.zshrc; for Bash, run source ~/.bashrc. If you skip this, typing octop will return a command-not-found error.

How Do You Install Octop on macOS, Linux, and Windows?

On macOS and Linux, use the one-line installer.

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

On Windows PowerShell, use this command.

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

Windows cmd users can download install.bat and run it, or execute it from a cloned repository.

The installer has two optional extras. Browser automation requires Playwright Chromium; add --extras browser during installation. Feishu channel support requires --extras channels-feishu.

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

Full installation options are in scripts/README.md, including --version, --from-source, --mirror, and their Windows equivalents.

If you already manage your own Python environment, you can install from PyPI.

pip install octop
# Optional: pip install "octop[browser]"
# Optional local ONNX embedding model cache: pip install "octop[local-embedding]"

The local embedding extra does one thing: it downloads the catalog model to ~/.octop/embedding_models. It is not used for chat and does not connect to Memory, so do not assume that installing it enables local inference.

For source development with uv:

uv sync --extra local-embedding

Desktop clients are available from GitHub Releases. Windows uses an NSIS installer, macOS uses a dmg, and Linux uses a tar.gz. FnOS NAS users can choose an fpk package, either Docker-dependent or native, and install it through the app center. Desktop client documentation is in desktop/README.md, and FnOS packaging guidance is in fnos/README.md.

How Do You Start Octop and Deploy It with Docker?

Start it in the foreground with one command.

octop run

It listens on http://127.0.0.1:8088 by default and starts both the API and the web console. To change the host and port:

octop run --host 0.0.0.0 --port 8088

To keep it running in the background, register it as a system service.

octop service start

This supports systemd, launchd, and Windows services.

Docker is better suited for production deployment. Use Compose to start it with one command.

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

Or build manually and run:

bash docker/docker_build.sh
docker run -d \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  -e OCTOP_DEFAULT_PASSWORD="<custom strong password; leave empty to auto-generate>" \
  octop:latest

Open http://localhost:8088. The first initialization creates an admin account and writes credentials to /data/.octop/credential.txt inside the container. If OCTOP_DEFAULT_PASSWORD is not set, a random strong password is generated automatically. If you set your own password, it must be at least 8 characters and include both letters and numbers. Common weak passwords rejected by the application’s password policy are automatically replaced with a random password. The admin username defaults to admin and can be overridden with OCTOP_ADMIN_USERNAME.

Docker-related environment variables:

The interactive octop init and setup wizard let you set your own password, with the same rule: at least 8 characters, with both letters and numbers. API docs are disabled by default. To enable them, set "enable_api_docs": true in config.json, then visit /api/docs.

Where Does Octop Store Data?

This is the first thing to understand in any self-hosted setup. All runtime data lives under ~/.octop/. The structure is as follows.

~/.octop/                          ← Installation and data root
├── config.json                    # Process configuration (optional database section)
├── octop.db                       # Default SQLite control plane (users, agents, channels, cron jobs …)
├── secrets/                       # JWT keys, channel tokens
├── agents/<agent_id>/             # Agent workspaces (SOUL.md, skills …)
├── security/tool_guard/           # Shell command allow/deny rules
├── logs/                          # Runtime logs
├── venv/                          # uv-managed Python (installer layout)
└── bin/octop                      # PATH wrapper → venv/bin/octop

The control plane uses SQLite with WAL mode by default. To switch to PostgreSQL, configure the database section in config.json, use OCTOP_DATABASE_* environment variables, or choose it in the first-run setup wizard. When the control plane is PostgreSQL, agent memory reuses the same DSN by default with per-agent schemas. If you want to keep file-based memory, set "memory": { "backend": { "type": "sqlite" } } in the agent configuration. See docs/configuration.md and docs/adr/002-database-backends.md for details.

Upgrade with octop update. It only replaces the wheel or binary. Your database, workspaces, keys, and config.json under ~/.octop/ are preserved. Database schema migrations run automatically on the next startup. Only run octop init if the setup wizard prompts you to migrate. Back up before upgrading across versions with octop backup.

How Do You Configure Models and IM Channels?

The CLI covers most daily configuration.

octop models           # LLM providers and models
octop provider list    # List providers
octop channel list     # List IM channels
octop channel install  # Install a channel
octop skills list --agent main   # View skills by agent
octop cron list        # List cron jobs
octop user list        # Admin: list users

Supported LLM provider presets include OpenAI-compatible APIs, DashScope (Qwen), Ollama, and others. You can configure them in the console or per agent with octop provider.

For IM channels, each one requires different credentials. Check the table before configuring.

The web UI, IM, and cron jobs share the same message processing pipeline. Cron jobs are scheduled with APScheduler and can be configured with natural language or triggered with slash commands. This is useful for having an agent push content or run tasks on a daily schedule.

How Do You Organize Multiple Users and Agents?

Octop uses multi-user JWT authentication and supports an admin role. The first-run wizard is octop init. Each user can create multiple agents, and each agent has its own workspace, provider, channels, and cron jobs. This structure provides isolation for shared family use or small-team workflows.

Agent personalities come from two sources. There are 16 built-in MBTI personality templates, and you can also fully customize the system prompt. The expert library is scanned at startup from infra/agents/experts/library/. Drop configurations there and they appear in the selectable list.

Workspace backends support local disk, COS, S3, and other remote storage. All file operations for an agent stay within this isolation boundary.

What Can You Connect with ACP?

ACP stands for Agent Client Protocol, and Octop supports both directions.

The inbound direction lets external tools call your Octop agent. For example, it provides a stdio ACP service for IDEs such as Zed and OpenCode.

octop acp --agent main

The outbound direction lets Octop delegate tasks to external coding agents. Configure a Runner on the ACP page in the console (/acp), scoped globally per user. Then enable acp_runner for an agent, and you can delegate tasks directly in a conversation. Built-in outbound runners include OpenCode, CodeBuddy, Claude Code, and Codex. Full configuration is in docs/acp.md.

What Else Can Octop Do? Knowledge Base, Plugins, and More

The knowledge base uses document-based RAG retrieval. After you upload files, semantic search anchors the agent’s answers to your private corpus. This fits internal document Q&A and similar scenarios.

Plugins are managed with octop plugin and support third-party extensions. Built-in plugins are injected during installation and can be enabled with one click in the console.

Terminal AI+ is an interactive shell inside the browser, with AI-assisted command execution and troubleshooting. Browser AI+ is a headless Chromium browser session that supports web automation, screenshots, and remote control. Remote desktop lets you view the screen and control keyboard and mouse in the console across Linux, Windows, and macOS. For headless Linux, you can set up an isolated desktop with one click. The README does not go into more configuration details for these features; use the console alongside the documentation when you try them.

How Is Octop Architected?

Octop uses a single-process architecture. On startup, the entire state is rebuilt from the control plane database. It does not depend on an external message queue or middleware. All entry points are routed through the in-process HarnessProcessor.

OctopServer
 ├─ DatabasePool         SQLite (WAL) or PostgreSQL
 ├─ SharedServices       Dependency injection root — all repos and configuration
 ├─ ExpertCatalog        Scans agents/experts/library/ at startup
 ├─ UserManager
 │   └─ HarnessAgentManager (per user)
 │       └─ AgentRuntime (per agent)
 │           ├─ HarnessAgent      Agent runtime (harness-agent)
 │           ├─ HarnessProcessor  IM / UI / cron entry point
 │           ├─ ChannelManager    IM connections (harness-gateway)
 │           └─ CronManager       APScheduler
 └─ FastAPI app (uvicorn)

Four harness projects sit underneath. harness-agent handles model routing, tools, skills, and conversation checkpoints. harness-gateway normalizes inbound messages from various IM platforms into a unified pipeline. harness-memory provides layered memory and full-text search, so memory migrates with the workspace. harness-browser uses CDP for browser automation and supports persistent profiles. These four projects are being prepared for open source, and repository links will be added after release.

The tech stack table is worth keeping for reference.

Project structure: src/octop/ contains config.py (environment variable configuration), launch.py (OctopServer startup plus uvicorn), infra/ (business core with agents, gateway, cron, db, users, etc.), api/ (FastAPI routes, JWT, SSE), cli/ (Click commands), and dashboard/ (built React SPA). Frontend source is in the repository root under dashboard/; after editing, run make build-frontend. docker/ holds Compose files, entry scripts, and build and deployment scripts. Tests are under tests/, split into unit/ and integration/.

How Do You Develop Octop Locally?

Prerequisites are Python 3.12+, Node 18+, and uv.

# Backend
make install          # pip install -e ".[dev]"
make all              # format-all + lint + typecheck + test (release gate)

# Frontend (separate terminal)
make dev-frontend     # Vite dev server :5173
make build-frontend   # Production build → src/octop/dashboard/
cd dashboard && npx tsc --noEmit

Run individual tasks with make test, make lint, make typecheck, or make format. Run make all before submitting a PR; it is the repository’s release gate.

Security and Privacy Notes

Local-first means configuration, conversations, workspaces, and credentials stay under ~/.octop/. Multi-user isolation separates agents and workspaces with JWT authentication. Sensitive data is automatically redacted before leaving the workspace, and high-risk tools or shell commands require explicit approval according to guardrail rules. Guardrail rules can be edited in ~/.octop/security/tool_guard/. LLM providers, storage backends, and IM channels can all be switched freely without locking you into a single vendor.

Quick Reference Checklist

• Before installing, confirm your system is macOS, Linux, or Windows. Python is not required.
• After installation, open a new terminal or source your shell config; otherwise octop will not be found.
• One-line install on macOS / Linux uses curl piped to bash; Windows uses irm piped to iex.
• Optional extras are added with --extras browser or --extras channels-feishu.
• Start with octop run (default http://127.0.0.1:8088); keep it running with octop service start.
• After Docker deployment, get the admin password from /data/.octop/credential.txt.
• Password rule: at least 8 characters, letters and numbers. Weak passwords are replaced with random ones.
• Data lives under ~/.octop/. Upgrade with octop update, back up with octop backup.
• To switch the control plane to PostgreSQL, edit the database section in config.json.
• ACP inbound uses octop acp --agent main; outbound is configured on the console /acp page with a Runner.

FAQ

Q: Do I need to install Python before installing Octop?
No. The installer uses uv to create an isolated Python 3.12 environment under ~/.octop/ and does not affect your system Python.

Q: Why does octop say command not found after installation?
Your current terminal has not loaded the new PATH. Open a new terminal, or run source ~/.zshrc / source ~/.bashrc.

Q: Where is the Docker admin password on first startup?
It is in /data/.octop/credential.txt inside the container. If OCTOP_DEFAULT_PASSWORD is not set, a random strong password is generated and written there.

Q: What is the default database, and can I change it?
The default is SQLite with WAL mode. You can switch to PostgreSQL in the database section of config.json, with OCTOP_DATABASE_* environment variables, or in the first-run setup wizard.

Q: Will upgrading lose data?
octop update only replaces the wheel or binary. The database, workspaces, keys, and config.json under ~/.octop/ are preserved. Schema migrations run automatically on the next startup. Back up with octop backup before upgrading across versions.

Q: Which external agents can ACP connect to?
Outbound built-in runners include OpenCode, CodeBuddy, Claude Code, and Codex. Inbound provides a stdio ACP service for Zed, OpenCode, and others.

Q: Why can’t I open the API docs?
They are disabled by default. Set "enable_api_docs": true in config.json, then visit /api/docs.

Q: How do I configure an agent’s personality?
There are 16 built-in MBTI templates, and you can also customize the system prompt. The expert library is scanned at startup from infra/agents/experts/library/.