Octop, TencentCloud's self-hosted assistant: one process, four composed runtimes, and an .env file with three uncommented runtime variables

One HarnessProcessor in process, with no external queue

Octop composes four separately versioned runtimes into a single Python process. Octop Harness is the agent runtime, carrying model routing, tools, skills and conversation checkpointing. Octop Gateway is the multi-platform IM bridge that normalizes incoming messages into one processing pipeline. Octop Memory provides hierarchical recall with full text search, so memory travels with the workspace. Octop Browser is the CDP based automation layer with persistent profiles for web tasks.

Instead of an external queue or message broker, every surface, meaning the web UI, IM and cron, is routed through one in-process HarnessProcessor. That is why the dashboard, the CLI, the IM channels and cron automation all come up together in a single `octop run`, with all data under `~/.octop/`, and why the process is described as restart safe.

What follows from that composition is that pinning the octop package does not pin what runs inside it. The dependency list gives octop-harness[all]>=1.0.6, octop-memory>=1.0.2, octop-gateway>=1.0.3 and octop-browser>=1.0.0, which are lower bounds, so a fresh install can resolve four different upstream versions from four different repositories.

SQLite in WAL mode by default, PostgreSQL by configuration

The control-plane database is SQLite in WAL mode by default, with PostgreSQL as the optional alternative. psycopg[binary]>=3.2 and langgraph-checkpoint-postgres>=2.0 sit in the core dependency list to back that switch, and the workspace backend, which can be local disk, a Docker sandbox, PostgreSQL or COS/S3, is a separate thing from this control plane.

Every key for the choice is present in the sample environment file, and every one of them is commented out:

# OCTOP_DATABASE_DRIVER=postgresql
# OCTOP_DATABASE_URL=postgresql://octop:[email protected]:5432/octop
# OCTOP_DATABASE_HOST=127.0.0.1
# OCTOP_DATABASE_PORT=5432
# OCTOP_DATABASE_NAME=octop
# OCTOP_DATABASE_USER=octop
# OCTOP_DATABASE_PASSWORD=
# OCTOP_DATABASE_SQLITE_PATH=octop.db

Docker users hit a named trap in the same file: docker/.env only interpolates variables, it does not auto-inject them into the container, so the identical keys have to be repeated under `environment:` in docker-compose.yml. On bare metal installations the same keys can live in ~/.octop/env instead. The sample SQLite path is left at the default octop.db, which is what puts the database file at ~/.octop/octop.db.

The bootstrap password only applies while ~/.octop/octop.db is missing

The first-run bootstrap variables fire only when ~/.octop/octop.db is absent, which means OCTOP_ADMIN_USERNAME and OCTOP_DEFAULT_PASSWORD do nothing at all after the first boot:

OCTOP_ADMIN_USERNAME=admin
OCTOP_DEFAULT_PASSWORD=
OCTOP_ADMIN_DISPLAY_NAME=Admin

The password policy sits in the comment directly above them: at least 8 characters with letters and digits, the same policy as change-password. Leave OCTOP_DEFAULT_PASSWORD empty, or set a password the policy rejects, and Octop starts the web setup wizard instead of silently creating a random admin; the wizard unlock password is written to ~/.octop/octop-login.txt.

A deployment that expects a fixed admin password has to supply it before the database exists.

Three uncommented runtime variables, and no OCTOP_LANGFUSE_ENABLED anywhere

Only three runtime variables are left uncommented in the sample file:

OCTOP_PORT=8088
OCTOP_LOG_LEVEL=info
OCTOP_BIND_HOST=0.0.0.0

OCTOP_BIND_HOST decides whether the dashboard listens on every interface, and 8088 is the port a plain `octop run` answers on. Model provider credentials, OPENAI_API_KEY and DASHSCOPE_API_KEY, are listed as optional and can equally be configured in the dashboard.

The observability section is the sharpest example of a variable that does not exist. There is no OCTOP_LANGFUSE_ENABLED. The on/off switch is the admin setting in the dashboard under Settings and Observability, stored as the settings key `observability_langfuse_enabled`. Anyone who writes an environment file to switch tracing off at boot will find nothing there to set.

Playwright and Pillow are core, so the browser and desktop extras barely add anything

The dependency list is long and uses lower bounds rather than exact pins for almost everything: fastapi>=0.110, uvicorn[standard]>=0.27, pydantic>=2.6,<2.14, langchain-core>=1.4.8, apscheduler>=3.10,<4, pyjwt>=2.8, argon2-cffi>=23.1, cryptography>=41, websockets>=13.0, mcp>=1.9,<2, boto3>=1.40.61 and ldap3>=2.9.1.

Two heavy pieces sit inside that core list. playwright>=1.40 drives the headless Chromium sessions behind Browser AI+, and pillow>=10.0 is a core dependency. The browser extra remains in the file anyway, with a comment saying it is kept for backward compatibility because playwright is now a core dependency, and it is a second copy of playwright>=1.40. A minimal install still carries a browser automation stack.

Document reading is core as well rather than optional: pypdf>=5.0, python-docx>=1.2.0, python-pptx>=1.0, openpyxl>=3.1, xlrd>=2.0.1 and pypinyin>=0.53 are all in the main list. The dev extra is kept so pip install -e ".[dev]" still works for legacy and CI flows, since uv sync reads [dependency-groups].dev instead.

make writes every target twice, once with uv and once without

The Makefile resolves its toolchain at parse time, so each target is written once for a machine with uv and once for a machine without it:

UV   := $(shell command -v uv 2>/dev/null)
RUN  := $(if $(UV),uv run,)
PYTHON := $(if $(UV),uv run python,python3)
PIP  := $(if $(UV),uv pip,python3 -m pip)
PYTEST_JOBS ?= auto

The default goal is help, make all runs formatting for backend and frontend, then backend lint, typecheck and test, which the file calls the ship bar. The React dashboard is built from dashboard/ into src/octop/dashboard, so the wheel carries the built frontend rather than the source tree. Publishing needs twine, installed with pip install twine or the make install-tools target, and the index is chosen by variable: PYPI_REPO ?= pypi, overridable as make publish PYPI_REPO=testpypi, with publish-test reserved for TestPyPI. PYTEST_JOBS ?= auto controls parallel workers for make test and make test-fast, and the documented override is make test PYTEST_JOBS=4. Stated prerequisites are Node.js with npm for the frontend, Python 3.12 or later for the backend, uv recommended or pip, and twine for publishing.

AgentTeams is Beta, and the extension points live in separate directories

The feature surface is wide. Security is described as built in, with JWT multi-user isolation, tool approval, shell command guardrails and PII redaction. Connectors reach the Tencent suite for Docs, Meeting and News, and an OAuth and MCP gateway extends the resource boundaries. Experts can be published and shared, including shared skill and sub-agent pools, alongside 16 MBTI persona templates with an interactive quiz. Memory comes from Octop Memory, which migrates with the workspace, and bundled plugins are seeded and toggled on demand. ACP delegation runs through `octop acp` for IDE and terminal work, delegating to OpenCode or Claude Code with permission gates. There is also a remote desktop for Linux, Windows and macOS, a one-click isolated desktop on headless Linux, and cron configured in natural language.

Two things are less settled. AgentTeams is marked Beta, and its coordinator, which schedules several experts on multi-step work, is documented in docs/expert-teams.md rather than in the overview. And the repository root carries dashboard/, desktop/, docker/, fnos/, plugins/, scripts/, docs/ plus mise.toml, uv.lock and .pre-commit-config.yaml, so a single `octop run` is only one of several buildable things in this tree.

The chat surface and the agent surface also rest on different footings. The dashboard, Feishu, DingTalk, QQ, WeChat, Telegram, Discord, WeCom and programmatic HTTP, SSE and WebSocket are all listed as ways in, but the only IM SDK in the pinned list is lark-oapi>=1.7.3, which is the Feishu client.

Editorial conclusion

Octop makes sense for a household or a small team that wants one process to serve a dashboard, a CLI, several IM channels and cron, and that is willing to run Python 3.12 alongside docker compose and Node.js. Before committing, read the Beta label on AgentTeams and the four runtimes the package composes, then check whether your own IM channel is covered by a pinned SDK, because only the Feishu client appears in the dependency list.

Frequently asked questions

Official sources

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