How Octop Works: Architecture Overview

Octop runs as a single process. Every surface — the web UI, the CLI, IM channel bridges, and cron automation — shares one SQLite database stored under ~/.octop/. When you restart Octop, the entire runtime state is rebuilt from ~/.octop/octop.db, so there are no external queues, brokers, or microservices to manage.

How the surfaces connect

All incoming messages, regardless of their origin, flow through a single unified processing pipeline inside Octop. The diagram below shows how the four surfaces funnel into that pipeline and share one database.

┌─────────────────────────────────────────────────────┐
│                    Octop (single process)            │
│                                                     │
│   ┌──────────────┐  ┌──────────────┐               │
│   │   Web UI     │  │  CLI / HTTP  │               │
│   └──────┬───────┘  └──────┬───────┘               │
│          │                 │                        │
│   ┌──────┴─────────────────┴───────┐               │
│   │           FastAPI app          │               │
│   └──────────────────┬─────────────┘               │
│                      │                             │
│   ┌──────────────┐   │   ┌──────────────┐          │
│   │  IM Channels │───┤   │     Cron     │          │
│   │  (platform   │   │   │  (scheduled  │          │
│   │   bridges)   │   │   │   prompts)   │          │
│   └──────┬───────┘   │   └──────┬───────┘          │
│          └───────────┼──────────┘                  │
│                      ▼                             │
│            ┌──────────────────┐                    │
│            │  Message router  │                    │
│            └────────┬─────────┘                    │
│                     │                              │
│            ┌────────▼─────────┐                    │
│            │   SQLite (WAL)   │  ~/.octop/octop.db │
│            └──────────────────┘                    │
└─────────────────────────────────────────────────────┘

The four surfaces

Surface	What it does
Web UI	Browser pages for chat, agent management, connectors, channels, cron, and settings
CLI	Terminal commands (`octop chats`, `octop agent`, `octop cron`, etc.) and ACP integration
IM Channels	Bridges to Feishu, WeCom, DingTalk, QQ, WeChat, Telegram, and other platforms
Cron	Scheduled tasks that send recurring prompts directly to your agents

Key concepts

Agents

Per-user AI assistants, each with their own workspace, LLM provider, skills, channels, and conversation history.

Experts & Personas

Bundled expert templates you can instantiate as agents, plus 16 MBTI personality profiles that shape how an agent communicates.

Channels

Messaging platform connections that route messages from Feishu, WeCom, DingTalk, QQ, WeChat, Telegram, and more to a specific agent.

Connectors

OAuth-authenticated apps and MCP gateways that give agents access to external services and tools.

Knowledge

Upload your files so agents can search them in chat and show cited sources.

Here is a brief description of each concept:

Agents

An agent is a personal AI assistant tied to one user. Each agent has an isolated workspace, its own LLM provider configuration, enabled skills, linked channels, and an independent conversation history. A single user can run multiple agents simultaneously — for example, one for coding and one for research.

Experts

Experts are pre-configured agent templates bundled with Octop. Octop scans its expert library at boot and makes them available for you to instantiate as real agents with a single command. Think of them as starting points that save you configuration time.

Personas

A persona is an MBTI personality profile that shapes the tone, communication style, and behaviour of an agent. Octop ships 16 built-in profiles — from The Architect (INTJ) to The Entertainer (ESFP). Assigning a persona writes a SOUL.md file into the agent's workspace, which becomes the backbone of its system message.

Channels

A channel connects one agent to an external IM platform. Once a channel is configured, messages sent to that platform are routed through Octop's IM bridge and delivered to that agent. Each agent can have multiple channels active at the same time.

Connectors

Connectors extend what an agent can do. OAuth connectors let the agent interact with external services (such as Tencent Docs or Weibo) after you authorize the connection. MCP gateways connect any Model Context Protocol-compatible tool server, making its tools available to the agent during chat.

Knowledge

A knowledge base is a collection of your files. After an administrator turns the feature on, agents search those files in chat and show cited sources under the reply.

Cron

Cron jobs let you schedule recurring prompts that are sent to an agent automatically. You can write them in natural language or as slash commands, and manage them from the web UI or via the CLI.

Data directory layout

All of Octop's runtime state lives under ~/.octop/. Nothing is stored in a remote database or cloud service.

~/.octop/                          ← install & data root
├── octop.db                       # SQLite — users, agents, channels, cron …
├── secrets/                       # JWT secret, channel tokens
├── agents/<agent_id>/             # per-agent workspace (SOUL.md, skills …)
├── security/tool_guard/           # shell command allow/deny rules
├── logs/                          # runtime logs
├── venv/                          # uv-managed Python environment
└── bin/octop                      # PATH wrapper → venv/bin/octop

NOTE

Because all data lives on your machine, you can back up or migrate a complete Octop installation by copying the ~/.octop/ directory. Use octop backup for a managed export.

Single-process advantages

Simple deployment — one octop run command starts everything.
Restart-safe — the process rebuilds all runtime state from octop.db on boot; no in-memory state is lost permanently.
No external dependencies — no Redis, no RabbitMQ, no separate worker processes.
Local-first privacy — all conversations, credentials, and workspaces stay on your machine.

How Octop Works: Architecture Overview#

#How the surfaces connect

#The four surfaces

#Key concepts

#Data directory layout