Octop explained: a self-hosted assistant for users, agents and channels
Deploying Octop: persistent state and a single-process control plane
Plan backup, listener access and restart behavior before connecting a team.
What you will learn
- Inventory all persistent state
- Review the service boundary
- Test restoration before rollout
Before you start
- Basic Python and service administration
- An isolated test environment
A proposed read-only dashboard makes unverified capabilities visible before use.
Key takeaways
- Backups must match actual storage layout.
- Automatic backup is not enabled by default in the dataclass.
- Local restoration cannot undo delivered messages.
Inventory all persistent state
The architecture separates a control-plane database from per-agent workspaces. A database-only backup may omit documents, skills and local conversation artifacts; inventory the actual backend layout first.
The configuration dataclass disables automatic backups by default and excludes chats from the default backup selection. Those defaults are not proof that a particular deployment has a complete recovery copy.
Review the service boundary
The README documents a system-service entry point and Docker packaging. Choose one operating model and record package or image revision, persistent volumes, credentials and listener configuration.
The inspected launch path composes the domain server with FastAPI and uvicorn. TLS dual-listener mode forces one worker and disables reload in this function. Do not assume increasing workers produces safe horizontal scaling.
Test restoration before rollout
Stop new scheduled and channel work during a recovery drill. Restore compatible database and workspace snapshots in an isolated environment, then verify ownership and one known task before admitting traffic.
No backup restore or production service deployment was executed here. Keep external actions in a separate ledger: restoring local state cannot retract messages already sent through a channel.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Inventory database and workspace state.
- 2
Record service, listener and version choices.
- 3
Verify a restoration drill before broader access.
Copy-ready example
deployment_record:
version: pinned
database: inventoried
workspaces: inventoried
listener: reviewed
restore_drill: required-before-rolloutFrequently asked questions
Is a database dump always enough?
No. Workspace and other selected content may live outside it.
Does a worker flag prove horizontal scaling?
No. Review the shared single-process responsibilities and test the chosen topology.
Sources
- Octop / README.mdSource checked 2026-09-23
- Octop / docs/architecture.mdSource checked 2026-09-23
- Octop / src/octop/config.pySource checked 2026-09-23
- Octop / src/octop/launch.pySource checked 2026-09-23