TencentCloud/Octop: a self-hosted multi-user AI assistant that runs as one Python process

The problem Octop solves: several people, several agents, one machine

Most self-hosted chat front ends assume one operator and one assistant. Octop's README targets a different shape: a household or a small team where one admin account serves several users, and each user gets more than one agent. Agents are per-user objects with their own workspace, providers, channels and cron jobs, and the README lists workspace backends of local disk, COS, S3 and other remote stores. The stated design goal is that every conversation, workspace and credential stays on your own machine while each user gets a personal team of specialists they switch between per task. The expert library is scanned at boot from infra/agents/experts/library/, so specialisation is a directory of files rather than a hosted marketplace. If you are one person running one assistant, that multi-user layer is overhead you will pay for and not use.

One process, one SQLite file: how the Harness stack fits together

Octop composes four runtimes from the Harness stack into a single process. harness-agent handles model routing, tools, skills and conversation checkpointing. harness-gateway normalises incoming IM messages from Feishu, DingTalk, QQ, Discord and WeCom into one pipeline. harness-memory provides hierarchical recall with full-text search. harness-browser drives CDP-based browser automation with persistent profiles. The README is explicit that there is no external queue or message broker: Web UI, IM and cron all route through one in-process HarnessProcessor, and the whole state is rebuilt from ~/.octop/octop.db on boot. The control plane is SQLite in WAL mode via aiosqlite, with PostgreSQL supported as an alternative through the OCTOP_DATABASE_* variables in .env.example. That single-process choice is the interesting trade-off. It removes the broker you would otherwise operate, and it also means the process is the system: restart-safe state is a property of the database file, not of a cluster. The README does not describe what happens to in-flight IM messages during a restart.

Installing Octop and running your first agent

The package is published on PyPI as octop, and pyproject.toml requires Python 3.12 or newer. The README points at `octop init` for first-run setup, which is where the wizard described under server and auth lives. The repository's own development flow, shown in the Makefile, prefers uv when it is available and falls back to plain commands otherwise:

uv run
uv pip
uv sync

The Makefile documents the frontend and backend development servers behind one target, and the wheel build separately:

make dev
make build

Once setup finishes, the README names the command that brings the surfaces up together:

octop run

The README also shows the inbound ACP server, which exposes your Octop agent over stdio to editors such as Zed and OpenCode:

octop acp --agent main

The .env.example file documents what the process reads at startup. It shows the runtime port, log level and bind host, and says to copy the file to deploy/.env or export it before `docker compose up`:

OCTOP_PORT=8088
OCTOP_LOG_LEVEL=info
OCTOP_BIND_HOST=0.0.0.0

The same file documents the first-run bootstrap. OCTOP_ADMIN_USERNAME defaults to admin, and leaving OCTOP_DEFAULT_PASSWORD empty auto-generates a random password written to ~/.octop/credential.txt:

OCTOP_ADMIN_USERNAME=admin
OCTOP_DEFAULT_PASSWORD=
OCTOP_ADMIN_DISPLAY_NAME=Admin

It also warns that docker/.env only interpolates and does not auto-inject into the container, so any database keys must also appear under environment: in docker-compose.yml. The interactive API docs at /api/docs are off by default; set "enable_api_docs": true in config.json to turn them on.

Where Octop is the wrong tool

The README's quick-start section is the weakest part of an otherwise detailed document. The .env.example file warns that docker/.env only interpolates and does not auto-inject into the container, so the database variables must also be listed under environment: in docker-compose.yml. That is a real trap: a Compose deployment can come up healthy while ignoring the PostgreSQL settings you thought you set. The same file notes that OCTOP_DEFAULT_PASSWORD is only used when ~/.octop/octop.db is absent, and that leaving it empty auto-generates a random password written to ~/.octop/credential.txt. Nothing in the README describes backup, restore or migration of that database, which is the entire state of the system. If you need a documented upgrade path, a supported HA topology, or an assistant that is not tied to a Python 3.12+ runtime, Octop is the wrong choice. It is also a poor fit if you want a managed service: the whole point is that the data stays local.

Octop compared with a general-purpose agent framework

A framework such as LangGraph or a bare agent runtime gives you primitives and expects you to build the surfaces. Octop takes the opposite position: it ships the surfaces. langchain-core and langgraph-checkpoint-postgres appear in the dependency list, so Octop is not replacing that layer so much as wrapping it in a product. The concrete difference is the multi-user JWT layer with an admin role, the IM channel bridge, the cron scheduler backed by APScheduler, and the dashboard, all of which you would otherwise assemble yourself. The cost is that you inherit Octop's opinions about where state lives and how messages are routed. If your requirement is a custom pipeline with your own queue and your own front end, a framework leaves you more room. If your requirement is a working assistant for four people by the end of the week, the framework leaves you more work.

Licence, maintenance and what an upgrade costs

Octop is MIT licensed, and pyproject.toml declares license = { text = "MIT" }. MIT is permissive: you can use, modify and redistribute it, including in commercial settings, provided the copyright notice and permission notice are preserved. That is a summary of the licence text, not legal advice; read LICENSE in the repository for the binding terms. One detail worth noticing is that pyproject.toml declares version 1.0.0 while the README badge and the most recent release both say 0.9.32. The release history shows a steady cadence, with v0.9.32 on 2026-09-06, v0.9.31 on 2026-09-01 and v0.9.28 on 2026-08-26, and the last push to the repository was on 2026-09-10. The practical upgrade cost is the database: because state is rebuilt from ~/.octop/octop.db, an upgrade that changes the schema touches the one file you cannot easily recreate. The README does not document a migration tool, so treat the release notes and CHANGELOG.md as the place to check before pulling a new version.

Editorial conclusion

Adopt Octop if you want one restart-safe process serving a dashboard, CLI, IM channels and cron for several users, and you are comfortable with Python 3.12+, an MIT licence and state that lives under ~/.octop/. Do not adopt it if you need a documented Docker Compose walkthrough, a published backup or restore procedure, or a stable API surface: the README describes the architecture but leaves those operational details to the repository. Verify first that the container path actually starts in your environment, that the SQLite file under ~/.octop/ is on storage you back up, and that your model provider credentials work through the dashboard before you move real conversations onto it.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. TencentCloud/Octop on GitHub