TencentCloud/Octop

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 | | 🤝 | Expert sharing | Publish experts and shared skill/sub-agent pools so teammates reuse proven setups instead of rebuilding them | | 🎭 | 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 | | 💾 | 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.

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

🤔 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:

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

Full setup: docs/acp.md.

🧭 Roadmap

Here are our mid-to-long term plans:

Shipped

• [x] Shared resource pool — a central pool of skills and sub-agents that any user can drop into a new expert without rebuilding from scratch.
• [x] Expert sharing — publish your experts to other users in the same deployment, so good configurations are reused instead of recreated.
• [x] PC client — native desktop apps for Windows / macOS / Linux alongside the web dashboard and IM channels.

• [ ] 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.

• [ ] 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.

🚀 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-.exe (64-bit) / Octop-desktop-windows-arm64-.exe (ARM64) — NSIS installer | | macOS | Octop-desktop-darwin-arm64-.dmg (Apple Silicon) / Octop-desktop-darwin-amd64-.dmg (Intel) | | Linux | Octop-desktop-linux-amd64-.tar.gz / Octop-desktop-linux-arm64-.tar.gz | | FnOS NAS | Octop-fnos-docker-.fpk (recommended on ARM; amd64/arm64 image) / Octop-fnos-native-.fpk (x86_64, no Docker) / Octop-fnos-native-arm64-.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, 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).

Docker (recommended for production)

# 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="" \
  octop:latest

octop update          # fetch and install the latest octop, then restart the service if one is registered

# 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

~/.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