A smarter, self-hosted AI assistant — multi-user, multi-agent.
Highlights · Overview · Core Technology · Features · Roadmap · Quick Start · Contents
English · 中文
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.
| Feature | Description | |
|---|---|---|
| 👥 | Multi-user expert team | One admin, shared household; built-in expert library — switch specialists per scenario |
| 🎭 | MBTI personas | 16 personality templates plus an interactive quiz — give each agent a distinct character |
| 🔒 | Security built-in | JWT multi-user isolation, tool approval, shell command guardrails, and PII redaction — data stays local |
| 🔌 | 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 |
|
| 💻 | Terminal AI+ | Interactive shell in the browser — AI-assisted command execution and troubleshooting |
| 🌐 | Browser AI+ | Headless Chromium sessions for web automation, screenshots, and remote browsing |
| 🖥️ | Remote desktop | Live screen and input from the dashboard on Linux, Windows, and macOS — remote office work and GUI apps; one-click isolated desktop on headless Linux |
| 🏠 | Self-hosted | Dashboard, CLI, IM channels, and cron in one octop run — all data under ~/.octop/ |
Octop is a self-hosted AI assistant platform for households and small teams. It runs a single process that serves a web dashboard, a CLI, IM channels (Feishu, DingTalk, QQ, Discord, WeCom, and more), and cron automation — all sharing one SQLite database under ~/.octop/.
Octop's design goal: keep every conversation, workspace, and credential on your own machine, while giving each user a personal team of specialized agents they can switch between per task.
| Layer | Technology |
|---|---|
| Language | Python 3.12+ |
| Web framework | FastAPI + uvicorn |
| Agent runtime | harness-agent |
| Gateway | harness-gateway |
| 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 |
Octop is built on the Harness stack — a set of focused runtimes that Octop composes into one process:
- harness-agent — Agent runtime: model routing, tools, skills, and conversation checkpointing.
- harness-gateway — multi-platform IM channel bridge that normalizes incoming messages into a single processing pipeline.
- harness-memory — hierarchical recall with full-text search, so an agent's memory travels with its workspace.
- harness-browser — CDP-based browser automation with persistent profiles for web tasks.
Instead of an external queue or message broker, Octop routes every surface — Web UI, IM, and cron — through one in-process HarnessProcessor. The result is a single, restart-safe process whose entire state is rebuilt from ~/.octop/octop.db on boot.
- Multi-user JWT authentication with admin role
- First-run setup wizard (
octop init) - Interactive API docs at
/api/docs(off by default — set"enable_api_docs": trueinconfig.jsonto enable)
- 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
- 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
- Web dashboard — chat, agents, connectors, channels, cron, settings
- CLI —
octop run,octop chat,octop acp, admin commands - HTTP/SSE API — full programmatic access
Octop supports ACP in two directions:
-
Inbound — external tools use your Octop agent
octop acp --agent main # stdio ACP server for Zed, OpenCode, … -
Outbound — Octop delegates to external coding agents
- Dashboard → ACP (
/acp): configure runners (global per user) - Enable acp_runner per agent, then delegate in chat
- Dashboard → ACP (
Built-in outbound runners include OpenCode, CodeBuddy, Claude Code, and Codex.
Full setup: docs/acp.md.
Here are our mid-to-long term plans:
- Shared resource pool — a central pool of skills and sub-agents that any user can drop into a new expert without rebuilding from scratch.
- Expert sharing — publish your experts to other users in the same deployment, so good configurations are reused instead of recreated.
- Browser & terminal polishing — browser skill recording (capture a workflow and replay it as a skill) and a more capable terminal AI assistant.
- AgentTeams — let one coordinator autonomously schedule and orchestrate multiple experts to tackle multi-step tasks.
- Self-evolution — automatically distill everyday conversations into reusable skills, so the assistant grows with you.
- PC / mobile clients — native desktop and mobile apps alongside the web dashboard and IM channels.
This roadmap may shift as the community grows; treat it as indicative only.
- macOS / Linux / Windows
- No pre-installed Python required — the installer uses uv to provision Python 3.12 in an isolated venv under
~/.octop/
macOS / Linux — one-line installer (recommended):
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bashWindows (PowerShell):
irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iexWindows (cmd) — download and run, or from a cloned repo:
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.bat -o install.bat
install.batAfter installation, open a new terminal or reload your shell:
source ~/.zshrc # Zsh
# or
source ~/.bashrc # BashThe installer places octop on your PATH via ~/.octop/bin. Optional extras:
# Browser automation (Playwright Chromium)
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras browser
# Feishu channel support
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras channels-feishuSee scripts/README.md for all install options (--version, --from-source, --mirror, Windows flags).
Desktop app (GUI, no terminal) — grab the artifact for your platform from GitHub Releases:
| Platform | Artifact |
|---|---|
| Windows | Octop-desktop-windows-amd64-<version>.exe (64-bit) / Octop-desktop-windows-arm64-<version>.exe (ARM64) — NSIS installer |
| macOS | Octop-desktop-darwin-arm64-<version>.dmg (Apple Silicon) / Octop-desktop-darwin-amd64-<version>.dmg (Intel) |
| Linux | Octop-desktop-linux-amd64-<version>.tar.gz / Octop-desktop-linux-arm64-<version>.tar.gz |
| FnOS NAS | Octop-fnos-docker-<version>.fpk (Docker-backed) / Octop-fnos-native-<version>.fpk (no Docker) — install via App Center |
See desktop/README.md for the desktop shell and fnos/README.md for the FnOS packaging guide.
Alternative — PyPI (if you already manage Python yourself):
pip install octop
# optional: pip install "octop[browser]"
# optional local ONNX embedding model cache (Models → Local): pip install "octop[local-embedding]"
# Downloads catalog weights under ~/.octop/embedding_models; not chat, not Memory.From a source checkout with uv:
uv sync --extra local-embeddingoctop initThe interactive wizard creates the SQLite database, JWT secret, and first admin account under ~/.octop/.
# Foreground (API + Web dashboard)
octop run
# Custom host / port
octop run --host 0.0.0.0 --port 8088
# Register as a system service (systemd / launchd / Windows service)
octop service startOpen http://127.0.0.1:8088. With Docker first-run defaults, sign in as admin / Octop123 and change the password immediately. Interactive octop init / the setup wizard asks you to choose a password (≥8 characters, letters and digits).
# Build and start
docker compose -f docker/docker-compose.yml up -d
# Or build manually
bash docker/docker_build.sh
docker run -d \
-p 8088:8088 \
-v octop-data:/data/.octop \
-e HOME=/data \
-e OCTOP_DEFAULT_PASSWORD=Octop123 \
octop:latestOpen http://localhost:8088. First boot creates an admin account with fixed default credentials admin / Octop123 (written to /data/.octop/credential.txt in the container) — not a randomly generated password. Override the defaults via OCTOP_ADMIN_USERNAME / OCTOP_DEFAULT_PASSWORD.
Password policy: at least 8 characters with letters and digits.
| Variable | Default | Description |
|---|---|---|
OCTOP_PORT |
8088 |
HTTP listen port |
OCTOP_DEFAULT_PASSWORD |
Octop123 |
First-run admin password (Docker bootstrap) |
OCTOP_ADMIN_USERNAME |
admin |
First-run admin username |
OCTOP_DATA |
~/.octop |
Host data directory (compose bind mount) |
See .env.example for the full list.
- Highlights
- Overview
- Core Technology
- Features
- Quick Start
- Deploy & Use
- Architecture & Dev
- Project Info
| Method | Platform | Description |
|---|---|---|
| Remote one-liner | macOS / Linux | curl …/octop/install.sh | bash |
| Remote one-liner | Windows | irm …/octop/install.ps1 | iex or install.bat |
| Local script | macOS / Linux | bash scripts/install.sh |
| Local script | Windows | scripts\install.bat or install.ps1 |
| PyPI | Any | pip install octop or pip install "octop[browser]" |
| Docker | Any | docker/docker-compose.yml |
All install scripts provision an isolated environment at ~/.octop/venv and a ~/.octop/bin/octop wrapper — they do not touch system Python.
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 listOpenAI-compatible APIs, DashScope (Qwen), Ollama, and other presets — configure per agent in the dashboard or via octop provider.
| Channel | Credentials |
|---|---|
| Feishu | App ID, App Secret |
| DingTalk | App Key, App Secret |
| Bot AppID, Token | |
| Discord | Bot Token |
| WeCom | Corp ID, Agent Secret |
| Web Dashboard | Enabled by default |
| Command | Description |
|---|---|
octop init |
Bootstrap ~/.octop/ (DB, admin, JWT secret) |
octop run |
Start Octop in the foreground |
octop service start |
Install and start as a system service |
octop service stop |
Stop the system service |
octop agent |
Create, list, start/stop agents |
octop channel |
Install and manage IM channels |
octop chats |
REPL and session management |
octop acp |
Stdio ACP server for IDE integration |
octop cron |
Manage scheduled tasks |
octop models |
Provider presets and model resolution |
octop skills |
Enable/disable per-agent skills |
octop backup |
Export / restore backups |
octop clean |
Remove CLI state or wipe ~/.octop/ |
octop update |
Check for and install updates |
Full reference: docs/cli.md.
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)
~/.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.
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.
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/
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 --noEmitIndividual targets: make test, make lint, make typecheck, make format.
- 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.
Contributions are welcome:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Run
make all(backend) ormake check-all(full stack) before submitting - Open a Pull Request
See CONTRIBUTING.md for the full guide. Security issues: SECURITY.md.
Module boundaries and coding conventions: AGENTS.md.
See CHANGELOG.md for release history.
| Project | Description |
|---|---|
| harness-agent | Agent runtime — model routing, tools, skills, checkpointing |
| harness-gateway | Multi-platform IM channel bridge |
| harness-memory | Hierarchical recall and FTS search |
| harness-browser | CDP browser automation with persistent profiles |
These
harness-*projects are being prepared for open-sourcing; repository links will be added once they are published.
For the customer WeCom support group, scan:
Please scan the QR code to join the group. For any questions or assistance, please contact the group admin directly.
This project is licensed under the MIT License.
Thanks to all contributors: