Browse by type

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/WebSocket. 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 |
| 📚 | Knowledge base | RAG over your documents; semantic retrieval grounds agent answers in your private corpus |
| 🧩 | 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 |
| 🏠 | 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 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
| Layer | Technology |
|---|---|
| Language | Python 3.12+ |
| Web framework | FastAPI + uvicorn |
| Agent runtime | harness-agent |
| Gateway | harness-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 Harness stack — a set of focused runtimes that Octop composes into one process:
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).
octop init)/api/docs (off by default — set "enable_api_docs": true in config.json to enable)infra/agents/experts/library/)octop run, octop chat, octop acp, admin commandsoctop plugin); bundled plugins are seeded and toggled on demand from the dashboardOctop supports ACP in two directions:
Inbound — external tools use your Octop agent
bash
octop acp --agent main # stdio ACP server for Zed, OpenCode, …
Outbound — Octop delegates to external coding agents
/acp): configure runners (global per user)Built-in outbound runners include OpenCode, CodeBuddy, Claude Code, and Codex.
Full setup: docs/acp.md.
Here are our mid-to-long term plans:
This roadmap may shift as the community grows; treat it as indicative only.
~/.octop/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:
# 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-feishu
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 (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-embedding
octop init
The 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 start
Open http://127.0.0.1:8088. With Docker, the first init generates a random admin password (written to /data/.octop/credential.txt) unless OCTOP_DEFAULT_PASSWORD is set. 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="<strong-password-or-omit-for-random>" \
octop:latest
Open http://localhost:8088. First boot creates the admin account and writes the credentials to /data/.octop/credential.txt in the container. With OCTOP_DEFAULT_PASSWORD unset a strong random password is generated; a password you set must be ≥8 characters with letters and digits (weak/commo
browse all types & interfaces →
$ claude mcp add Octop \
-- python -m otcore.mcp_server <graph>