openkube/octop repository overview

Octop is an open-source, self-hosted AI assistant. It's not just a tool — it's a digital life form that can operate in parallel. Through its multi-agent architecture, it builds an intelligent environment that is both independent and collaborative for teams, families, and individuals. Best of all, it runs entirely on your machine — the fully self-hosted design means privacy is never a compromise, while single-process startup makes the powerful web console, CLI, and IM integrations readily accessible.

Chat through the Web Dashboard, Feishu, DingTalk, QQ, Discord, WeCom, or programmatic HTTP/SSE. Extend capabilities with the expert library, Connectors (OAuth + MCP), and ACP integration for IDE workflows.

⁠Docker (recommended for production)

docker run -d \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  -e OCTOP_DEFAULT_PASSWORD=Octop123 \
  openkube/octop:latest

Open http://localhost:8088 — default credentials are admin / Octop123 (change immediately). Credentials are also written to /data/.octop/credential.txt on first boot.

> Password policy: at least 8 characters with letters and digits. A future release may replace the fixed Docker default with a randomly generated password written only to credential.txt.

⁠⚙️ Configuration

All runtime state lives in ~/.octop/. Manage it via CLI or edit files directly.

# LLM providers and models
octop models
octop provider list

# IM channels
octop channel list
octop channel install

# Skills (per agent)
octop skills list --agent main

# Cron jobs
octop cron list
octop cron create --help

# Users (admin)
octop user list

⁠Supported LLM providers

OpenAI-compatible APIs, DashScope (Qwen), Ollama, and other presets — configure per agent in the dashboard or via octop provider.

⁠Supported channels

⁠📖 CLI reference

Full reference: docs/cli.md⁠.

⁠🖥️ Web dashboard

After octop run, open http://127.0.0.1:8088⁠.

- Chat — real-time conversation with agents - Agents — create agents, pick experts / MBTI personas, configure providers - Connectors — OAuth apps and MCP gateways - Channels — IM platform setup - Cron — visual cron job management - ACP — configure outbound coding-agent runners - Settings — users, security, TLS, system

Interactive API docs: http://127.0.0.1:8088/api/docs⁠ (disabled by default — enable by setting "enable_api_docs": true in config.json)

⁠📁 Data directory

~/.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 (installer layout)
└── bin/octop                      # PATH wrapper → venv/bin/octop

See docs/configuration.md⁠ for env vars and config.json.

⁠🏗️ Architecture

OctopServer
 ├─ SqlitePool               SQLite (WAL mode)
 ├─ SharedServices       DI root — every repo + config
 ├─ ExpertCatalog        scans agents/experts/library/ at boot
 ├─ UserManager
 │   └─ HarnessAgentManager (per user)
 │       └─ AgentRuntime (per agent)
 │           ├─ HarnessAgent      Agent runtime (harness-agent)
 │           ├─ HarnessProcessor  IM / UI / cron entry point
 │           ├─ ChannelManager    IM connections (harness-gateway)
 │           └─ CronManager       APScheduler
 └─ FastAPI app (uvicorn)

Single process. Restart rebuilds state from ~/.octop/octop.db.

See docs/architecture.md⁠ and docs/adr/001-single-process-model.md⁠.

⁠📁 Project layout

src/octop/
  config.py    env-var config
  launch.py    OctopServer boot + uvicorn
  infra/       business core (agents, gateway, cron, db, users, …)
  api/         HTTP layer — FastAPI app, routers, JWT, SSE
  cli/         CLI layer — Click commands
  dashboard/   built React SPA (wheel artifact)

dashboard/     frontend source (Vite) — edit here, run make build-frontend

docker/        Docker Compose, entrypoint, build & deploy scripts
tests/         unit/ + integration/

⁠🛠️ Development

Prerequisites: Python 3.12+, Node 18+, uv⁠

# Backend
make install          # pip install -e ".[dev]"
make all              # format-all + lint + typecheck + test (ship bar)

# Frontend (separate terminal)
make dev-frontend     # Vite dev server on :5173 (override with VITE_DEV_PORT)
make build-frontend   # production build → src/octop/dashboard/
cd dashboard && npx tsc --noEmit

Individual targets: make test, make lint, make typecheck, make format.

⁠🔒 Security & privacy

- Local-first: Config, chats, workspaces, and credentials live under ~/.octop/ on your machine. - Multi-user isolation: JWT auth with per-user agents and workspaces. - Tool guardrails: User-editable shell command rules under ~/.octop/security/tool_guard/. - No vendor lock-in: Swap LLM providers, storage backends, and channels without rewriting agents.