octop 0.1.0.dev0

Multi-user, multi-Agent self-hosted AI server built on harness-agent

Octop

Multi-user, multi-Agent self-hosted AI server — one process, no external queue.

English · 中文

---

Octop is an open-source, self-hosted AI control plane built on the Harness agent stack. One Python process runs the dashboard, CLI, IM channels, cron jobs, and multi-user agent runtime — no external queue required.

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.

✨ Highlights

	Feature	Description
👥	Multi-user expert team	One admin, shared household; built-in expert library and MBTI personas — switch roles per scenario
🔌	Connector ecosystem	Tencent suite (Docs, Weibo trends, News, …); OAuth and MCP gateway extend resource boundaries
💾	Pluggable backends	Local disk, Docker containers, PostgreSQL, or COS/S3 — AI operates inside isolated boundaries
🧠	Portable memory	Powered by harness-memory; memory migrates with the workspace
↔️	ACP bidirectional	octop acp for IDE/terminal AI; delegate to OpenCode / Claude Code with permission gates
🏠	Single-process self-hosted	Dashboard, CLI, IM channels, and cron in one octop run — all data under ~/.octop/

🏗️ Tech Stack

Layer	Technology
Language	Python 3.11+
Web framework	FastAPI + uvicorn
Agent runtime	harness-agent + LangGraph
IM bridge	harness-im-bridge
Control plane DB	SQLite (WAL) via aiosqlite
Frontend	React 18 + TypeScript + Vite + Ant Design
Scheduling	APScheduler
ACP	agent-client-protocol
Build / quality	hatchling · ruff · mypy · pytest

🚀 Quick Start

Prerequisites

• Python 3.11+
• uv (recommended) or pip

Install & run

pip install octop
octop init        # interactive bootstrap: DB, JWT secret, first admin
octop run         # serve dashboard + API on :8088
open http://127.0.0.1:8088

Optional browser automation:

pip install "octop[browser]"

Docker (recommended for production)

# Build and start
docker compose -f deploy/docker-compose.yml up -d

# Or build manually
bash deploy/docker_build.sh
docker run -d \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  -e OCTOP_DEFAULT_PASSWORD=changeme \
  octop:latest

Open http://localhost:8088 — default credentials are admin / octop (change immediately).

Variable	Default	Description
OCTOP_PORT	8088	HTTP listen port
OCTOP_DEFAULT_PASSWORD	octop	First-run admin password
OCTOP_ADMIN_USERNAME	admin	First-run admin username
OCTOP_DATA	~/.octop	Host data directory (compose bind mount)

See .env.example for the full list.

📦 Install options

Command	Description
pip install octop	Core server — API, CLI, dashboard, IM bridge
pip install "octop[browser]"	Adds harness-browser for remote browser sessions
bash scripts/install.sh	One-line installer (macOS / Linux, PyPI or source)

🧩 Core capabilities

Server & auth

• Multi-user JWT authentication with admin role
• First-run setup wizard (octop init)
• Interactive API docs at /api/docs

Agents

• Multiple agents per user; each has its own workspace, providers, channels, and cron
• 16 MBTI persona templates + custom system prompt
• Expert library scanned at boot (infra/agents/experts/library/)
• Workspace backends: local disk, COS, S3, and other remote stores

Channels & automation

• IM channels: Feishu, DingTalk, QQ, Discord, WeCom, and more
• Proactive cron jobs with natural-language and slash-command triggers
• Unified message processing across Web UI, IM, and cron surfaces

Surfaces

• Web dashboard — chat, agents, connectors, channels, cron, settings
• CLI — octop run, octop chat, octop acp, admin commands
• HTTP/SSE API — full programmatic access

ACP (Agent Client Protocol)

Octop supports ACP in two directions:

1. Inbound — external tools use your Octop agent

   octop acp --agent main   # stdio ACP server for Zed, OpenCode, …
   

2. Outbound — Octop delegates to external coding agents

   • Dashboard → ACP (/acp): configure runners (global per user)
   • Enable acp_runner per agent, then delegate in chat

Built-in outbound runners include OpenCode, CodeBuddy, Qwen Code, Claude Code, and Codex.

Full setup: docs/acp.md.

🏗️ Architecture

OctopServer
 ├─ DBPool               SQLite (WAL mode)
 ├─ SharedServices       DI root — every repo + config
 ├─ ExpertCatalog        scans agents/experts/library/ at boot
 ├─ UserManager
 │   └─ HarnessAgentManager (per user)
 │       └─ AgentRuntime (per agent)
 │           ├─ HarnessAgent      LangGraph runtime (harness-agent)
 │           ├─ HarnessProcessor  IM / UI / cron entry point
 │           ├─ ChannelManager    IM connections (harness-im-bridge)
 │           └─ 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

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

🛠️ Development

Prerequisites: Python 3.11+, Node 18+, uv

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

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

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

📖 Documentation

Doc	Contents
docs/architecture.md	Layered diagram, process model
docs/configuration.md	~/.octop/ layout, env vars
docs/acp.md	ACP inbound and outbound
docs/api.md	Every route, body, error code
docs/cli.md	Every CLI subcommand
docs/personas.md	16 MBTI templates
docs/adr/	Architecture Decision Records
AGENTS.md	Guide for AI coding agents

🔒 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.

🤝 Contributing

Contributions are welcome:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run make all before submitting
4. Open a Pull Request

See AGENTS.md for module boundaries and coding conventions.

📋 Changelog

See CHANGELOG.md for release history.

🔗 Related projects

Project	Description
harness-agent	LangGraph agent runtime — model routing, tools, skills, checkpointing
harness-im-bridge	Multi-platform IM channel bridge
harness-memory	Hierarchical recall and FTS search
harness-browser	CDP browser automation with persistent profiles

📄 License

This project is licensed under the MIT License.

---

Made with ❤️ by the OrcaKit team