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, WeChat, Telegram, Discord, WeCom, or programmatic HTTP/SSE/WebSocket. 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 expert market — switch specialists per scenario |
| 🤝 |
Cloud collaboration |
Link this Octop to another instance to browse peer experts and chat across instances; history stays on the expert's side |
| 🎭 |
MBTI personas |
16 personality templates plus an interactive quiz — give each agent a distinct character |
| 🎯 |
AgentTeams (Beta) |
A coordinator schedules multiple experts on multi-step work; details |
| 🔒 |
Security built-in |
JWT multi-user isolation, tool approval, shell command guardrails, and PII redaction — data stays local |
| 🔌 |
Connector ecosystem |
Tencent suite (Docs, Meeting, News, …); OAuth and MCP gateway extend resource boundaries — supported connectors |
| 💾 |
Pluggable workspace backends |
Local disk, Docker sandbox, PostgreSQL, or COS/S3 for agent files — separate from the control-plane DB |
| 🧠 |
Portable memory |
Powered by Octop Memory; memory migrates with the workspace |
| 📚 |
Knowledge base |
RAG over your documents; share corpora within a deployment and ground answers in your private data |
| 🧩 |
Plugins |
Extend Octop with third-party plugins; bundled plugins are seeded and toggled on demand |
| ↔️ |
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 |
| 🪟 |
Desktop client |
Native Windows / macOS / Linux apps (and FnOS packages) alongside the web dashboard |
| 🏠 |
Self-hosted |
Dashboard, CLI, IM channels, and cron in one octop run — all data under ~/.octop/ |
📌 Overview
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, WeChat, Telegram, Discord, WeCom, and more), and cron automation — all sharing one control-plane database under ~/.octop/ (SQLite by default; PostgreSQL optional).
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.
🐾 What can you do with Octop
- Personal assistant — let a dedicated agent write weekly reports, organize notes, and manage your schedule; memory persists with the workspace.
- Family sharing — one admin account, the whole household; assign different agents and experts per member; share experts and knowledge bases when useful.
- Team helper — AgentTeams or parallel agents, bridging Feishu / DingTalk / WeCom / WeChat to route tasks into group chats.
- Developer boost — delegate coding tasks to OpenCode / Claude Code via ACP, or troubleshoot from the terminal with AI assistance.
- Web automation — use Browser AI+ and remote desktop for forms, screenshots, and GUI apps.
- Scheduled tasks — configure cron in natural language so the agent pushes or runs jobs on time every day.
🧠 Core Technology
| Layer |
Technology |
| Language |
Python 3.12+ |
| Web framework |
FastAPI + uvicorn |
| Agent runtime |
Octop Harness |
| Gateway |
Octop Gateway |
| Control plane DB |
SQLite (WAL, default) or PostgreSQL (optional) |
| Frontend |
React 18 + TypeScript + Vite + Ant Design |
| Scheduling |
APScheduler |
| ACP |
agent-client-protocol |
| Build / quality |
hatchling · ruff · mypy · pytest |
Octop is built on the Octop Harness stack — a set of focused runtimes that Octop composes into one process:
- Octop Harness — Agent runtime: model routing, tools, skills, and conversation checkpointing.
- Octop Gateway — multi-platform IM channel bridge that normalizes incoming messages into a single processing pipeline.
- Octop Memory — hierarchical recall with full-text search, so an agent's memory travels with its workspace.
- Octop 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 the control-plane database on boot (local SQLite by default; PostgreSQL optional).
🤔 Features
Server & auth
- 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": true in config.json to enable)
Experts
- Multiple experts 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/); expert market and in-deployment expert sharing
- AgentTeams (Beta) — coordinator + member experts for multi-step tasks (docs/expert-teams.md)
- Workspace backends (expert files): local disk, Docker sandbox, PostgreSQL, COS/S3, and other remote stores — distinct from the control-plane database
Channels & automation
- IM channels: Feishu, DingTalk, QQ, WeChat, Telegram, 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, experts / teams, connectors, channels, cron, knowledge, plugins, settings
- Desktop client — native apps for Windows / macOS / Linux; FnOS packages for NAS
- CLI —
octop run, octop chats, octop acp, admin commands
- HTTP/SSE/WebSocket API — full programmatic access
- Remote desktop — dashboard control of the host desktop session
Knowledge & plugins
- Knowledge base — RAG over your documents; optional sharing within the same deployment
- Plugins — install and manage third-party plugins (
octop plugin); bundled plugins are seeded and toggled on demand from the dashboard
ACP (Agent Client Protocol)
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
Built-in outbound runners include OpenCode, CodeBuddy, Claude Code, and Codex.
Full setup: docs/acp.md.
🧭 Roadmap
Here are our mid-to-long term plans:
Shipped
- 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.
- PC client — native desktop apps for Windows / macOS / Linux alongside the web dashboard and IM channels.
In progress
- AgentTeams (Beta) — let one coordinator autonomously schedule and orchestrate multiple experts to tackle multi-step tasks.
- Mobile client (closed beta) — native mobile apps currently in internal testing.
Planned
- Browser & terminal polishing — browser skill recording (capture a workflow and replay it as a skill) and a more capable terminal AI assistant.
- Self-evolution — automatically distill everyday conversations into reusable skills, so the assistant grows with you.
- Managed Agents — platform-hosted agent lifecycle (provision, scale, and operate agents without managing the full self-hosted stack yourself).
- Project — project-scoped workspaces that group agents, files, and conversations around a shared goal.
- Cloud–edge continuum — run Octop locally while offloading selected tasks to the cloud, so light work stays on-device and heavier jobs use remote capacity when you need it.
- Plugin marketplace — a curated market to discover, install, and update third-party plugins without leaving Octop.
- Conversational control plane — deepen Octop’s own skills so chat can cover the full dashboard surface: create experts, wire channels, manage knowledge bases, and scaffold plugins end-to-end.
This roadmap may shift as the community grows; treat it as indicative only.
🚀 Quick Start
Prerequisites
- macOS / Linux / Windows
- No pre-installed Python required — the installer uses uv to provision Python 3.12 in an isolated venv under
~/.octop/
- A modern multi-core CPU with a few GB of RAM for the process plus model/embedding caches; enough disk for the database, agent workspaces, and document corpora
1. Install
macOS / Linux — one-line installer (recommended):
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash
Windows (PowerShell):
irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iex
Windows (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.bat
After installation, open a new terminal or reload your shell:
source ~/.zshrc # Zsh
# or
source ~/.bashrc # Bash
The installer places octop on your PATH via ~/.octop/bin. Optional extras:
# Download Playwright Chromium for browser automation (skipped if a system Chrome/Chromium is already present)
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras browser
See 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 (recommended on ARM; amd64/arm64 image) / Octop-fnos-native-<version>.fpk (x86_64, no Docker) / Octop-fnos-native-arm64-<version>.fpk (ARM64 fallback if 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 local ONNX embedding model cache (Models → Local): pip install "octop[local-embedding]"
# Downloads catalog weights under ~/.octop/embedding_models; not chat, not Memory.
# Browser automation uses the bundled Playwright package; install Chromium via the installer --extras browser,
# the dashboard, or: python -m playwright install chromium
From a source checkout with uv:
uv sync --extra local-embedding
2. Initialize
octop init
The interactive wizard creates the SQLite database, JWT secret, and first admin account under ~/.octop/.
3. Run
# 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 start
Open http://127.0.0.1:8088. With Docker, a valid OCTOP_DEFAULT_PASSWORD creates the admin on first boot (credentials in /data/.octop/credential.txt); if it is unset or rejected, open the setup wizard (unlock password in /data/.octop/octop-login.txt). Interactive octop init / the setup wizard asks you to choose a password (≥8 characters, letters and digits).
Docker (recommended for production)
# Build and start
docker compose -f docker/docker-compose.yml up -d
# China mirror when ghcr.io is unreachable (no local build)
docker compose -f docker/docker-compose.cn.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="<strong-password-or-omit-for-setup-wizard>" \
octop:latest
Open http://localhost:8088. A valid OCTOP_DEFAULT_PASSWORD creates the admin on first boot and writes credentials to /data/.octop/credential.txt. If it is unset or rejected by the password policy, no admin is created — complete the setup wizard (unlock password in /data/.octop/octop-login.txt). Override the username via OCTOP_ADMIN_USERNAME.
Password policy: at least 8 characters with letters and digits.
| Variable |
Default |
Description |
OCTOP_PORT |
8088 |
HTTP listen port |
OCTOP_DEFAULT_PASSWORD |
(unset) |
First-run admin password (Docker bootstrap). Valid → create admin; unset or rejected → setup wizard |
OCTOP_ADMIN_USERNAME |
admin |
First-run admin username |
OCTOP_DATA |
~/.octop |
Host data directory (compose bind mount) |
See .env.example for the full list.
Deploy with Cloud
📑 Contents
📦 Install options
| 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 (optional extras such as local-embedding) |
| Docker |
Any |
docker/docker-compose.yml; China mirror: docker/docker-compose.cn.yml |
All install scripts provision an isolated environment at ~/.octop/venv and a ~/.octop/bin/octop wrapper — they do not touch system Python.
Upgrade
octop update replaces only the wheel/binary — your ~/.octop/ database, workspaces, secrets, and config.json are preserved:
octop update # fetch and install the latest octop, then restart the service if one is registered
The schema migrates automatically on next boot; run octop init only if the setup wizard prompts for a migration. Always back up first (octop backup) before a cross-version upgrade.
⚙️ 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
| Channel |
Credentials |
| Feishu |
App ID, App Secret |
| DingTalk |
App Key, App Secret |
| QQ |
Bot AppID, Token |
| WeChat |
QR bind / account credentials; CLI |
| Telegram |
Bot Token |
| Discord |
Bot Token; all accessible channels allowed by default, optional channel/DM allowlists; setup and testing |
| WeCom |
Corp ID, Agent Secret |
| Web Dashboard |
Enabled by default |
Other kinds (e.g. Yuanbao, Xiaoyi, MQTT) are available via the gateway — see channel setup in the dashboard or CLI.
Supported connectors
Built-in OAuth / MCP connectors include Tencent Docs, Tencent Meeting, Notion, TickTick, OpenAlex, Feishu CLI, WeCom CLI, Agent Mail, Obsidian, WeKnora, Dify, and more. Names and descriptions are localized (en / zh).
Full catalog, auth kinds, and MCP modes: docs/connectors.md. Custom MCP servers can be added in the dashboard.
📖 CLI reference
| 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 plugin |
Install and manage third-party plugins |
octop backup |
Export / restore backups |
octop clean |
Remove CLI state or wipe ~/.octop/ |
octop memory list |
List running agents eligible for memory maintenance; no database changes. |
octop memory slim [--agent ID] |
Back up and slim SQLite memory through the running host; uses the selected agent or prompts by number. Shows terminal and dashboard progress. Details |
octop memory slim --all |
Sequentially maintain all eligible running agents, with per-agent progress; stops on the first failure. |
octop update |
Check for and install updates |
In signed-in dashboard or local CLI chat, /memory slim explains maintenance for the current agent;
/memory slim --all lists your eligible agents. Add --confirm to start after reviewing the impact.
Use /memory status for progress/results. Chat stays available until maintenance is confirmed and begins.
External IM maintenance requires verified sender permissions and is not enabled yet.
Full reference: docs/cli.md.
🖥️ Web dashboard
After octop run, open http://127.0.0.1:8088.
- Chat — real-time conversation with experts and teams
- Experts — create experts, pick templates / MBTI personas, share or publish experts, configure providers
- AgentTeams (Beta) — coordinator + member experts for multi-step work
- Connectors — OAuth apps and MCP gateways
- Channels — IM platform setup
- Cron — visual cron job management
- Knowledge base — manage document corpora, semantic retrieval, and in-deployment sharing
- Plugins — install, enable, and configure plugins
- Remote desktop — live screen and input from the dashboard
- 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
├── config.json # process config (optional database section)
├── 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
The control plane can also use PostgreSQL — set database in config.json, or OCTOP_DATABASE_* / the first-run wizard. With PostgreSQL, agent memory reuses the same DSN by default (per-agent schema); to keep file-based memory, set "memory": { "backend": { "type": "sqlite" } } in the agent config. See docs/configuration.md and docs/adr/002-database-backends.md.
See docs/configuration.md for env vars and config.json.
🏗️ Architecture
OctopServer
├─ DatabasePool SQLite (WAL) or PostgreSQL
├─ SharedServices DI root — every repo + config
├─ ExpertCatalog scans agents/experts/library/ at boot
├─ UserManager
│ └─ HarnessAgentManager (per user)
│ └─ AgentRuntime (per agent)
│ ├─ HarnessAgent Agent runtime (octop-harness)
│ ├─ HarnessProcessor IM / UI / cron entry point
│ ├─ ChannelManager IM connections (octop-gateway)
│ └─ CronManager APScheduler
└─ FastAPI app (uvicorn)
Single process. Restart rebuilds state from the control-plane database (local SQLite by default; PostgreSQL optional).
See docs/architecture.md, docs/adr/001-single-process-model.md, and docs/adr/002-database-backends.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 -b
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.
- PII redaction & tool approval: sensitive data is redacted before it leaves the workspace, and risky tools or shell commands require explicit approval under the guardrail rules.
- 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:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature)
- Run
make all (backend) or make 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.
📋 Changelog
See CHANGELOG.md for release history.
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.
📄 License
This project is licensed under the MIT License.
✨ Contributors
Thanks to all contributors:
Octop 是一个开源、可自托管的 AI 助手平台，采用多智能体架构，面向个人、家庭和小团队，让你能完全在自己的机器上运行一支专属的 AI “专家”队伍。