Octop explained: a self-hosted assistant for users, agents and channels
Octop architecture: shared processing across web, IM and cron
Trace request surfaces into a process-wide runtime and distinct storage responsibilities.
What you will learn
- Follow the layers
- Understand user and agent ownership
- Keep transport details current
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
- One registry serves multiple agents.
- Row ownership differs from OS isolation.
- WebSocket and SSE serve different paths.
Follow the layers
The architecture places dashboard and CLI above FastAPI routes, then managers and processors above reusable harness libraries. The control database and file workspaces serve different persistence roles.
The documented design avoids a required external queue for the initial process model. That simplifies startup but concentrates lifecycle and resource coordination in one service; it is not an availability guarantee.
Understand user and agent ownership
The architecture describes a global agent registry and row-level ownership checks against the caller, with an administrator bypass. This is different from a separate isolated process for every user.
Those statements need route-level tests before treating a deployment as securely multi-tenant. This series does not audit every authorization path, backend adapter or administrator capability.
Keep transport details current
The architecture says dashboard streaming uses a WebSocket chat endpoint, while a resumed human-in-the-loop turn still uses SSE. Do not implement a client from an obsolete assumption that every chat stream is SSE.
The React frontend communicates through APIs rather than opening the database. When diagnosing a missing message, distinguish transport failure, session routing, model execution and persistence before changing configuration.
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
Map each surface to the processor.
- 2
Separate ownership checks from process isolation.
- 3
Verify the transport used by the chosen route.
Copy-ready example
web / IM / cron -> gateway and processor -> agent runtime
control database: users, providers, sessions
workspace backend: agent content and filesFrequently asked questions
Is every user a separate process?
The documented architecture uses a global registry in a single process.
Is all chat streaming SSE?
The architecture documents WebSocket chat and SSE for a resumed approval turn.
Sources
- Octop / docs/architecture.mdSource checked 2026-09-23