Architecture

Web / TUI / desktop / channels / MCP clients
                    │
             HTTP + WebSocket
                    │
          Hono API and gateway (:3005)
                    │
 root agent · delegated agents · tools · skills
                    │
       PGlite or PostgreSQL + pgvector

Octipus runs on Node.js. The backend exposes a Hono-compatible HTTP API and WebSocket gateway. The browser client is built with Vite, React 19, and React Router; the Tauri desktop app packages that client as a thin frontend.

A general root agent receives requests. It can act directly or delegate bounded work to specialist roles. Topic classification provides a routing hint; it is not a separate mandatory orchestration hop. Tools pass through parameter validation and permission policy before execution.

PGlite supports embedded local storage. External deployments use PostgreSQL with pgvector; PostgreSQL also backs caching, queueing, and pub/sub. The encrypted vault stores credentials. Authentication includes cookie sessions for browsers and bearer credentials for non-browser clients.

The standalone mcp-server/ package exposes Octipus capabilities to MCP clients and has its own dependencies, transport lifecycle, and authentication flow.

For authoritative module boundaries and generated inventories, see AGENT.md, DESIGN.md, and docs/architecture/ in the repository.