We open sourced Octop, a multi-user AI workspace for yourself, your family and your team.

Everyone gets their own login and can create multiple agents, each with its own workspace. Nothing you say or save shows up in another account. Almost everything can be swapped: models, storage, memory, plugins. Each agent comes with a browser, a terminal and a remote desktop.

You can hand off work to Claude Code, Codex, Cursor, OpenCode, CodeBuddy and other coding agents you already use. It also lives in your group chats on Telegram and Discord.

It runs on your own machine, and one command is all it takes: octop run.

The full picture is in the repo: http://github.com/TencentCloud/Octop….

TencentCloud/Octop

Source: https://github.com/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

📌 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

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:

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

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="<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/common passwords are rejected by the app password policy and fall back to a random one). Override the username via OCTOP_ADMIN_USERNAME.

Password policy: at least 8 characters with letters and digits.

See .env.example for the full list.

📑 Contents

• Highlights
• Overview
• Core Technology
• Features
• Roadmap
• Quick Start
• Deploy & Use
  • Install options
  • Configuration
  • CLI reference
  • Web dashboard
  • Data directory
• Architecture & Dev
  • Architecture
  • Project layout
  • Development
• Project Info
  • Security & privacy
  • Contributing
  • Changelog
  • Related projects
  • Community
  • License

📦 Install options

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

Other kinds (e.g. Yuanbao, Xiaoyi, MQTT) are available via the gateway — see channel setup in the dashboard or CLI.

📖 CLI reference

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:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run make all (backend) or make check-all (full stack) before submitting
4. 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.

🔗 Related projects

💬 Community

• Discord — join the English-speaking community: discord.gg/jPas5J8Ua

WeCom Customer Group (CN)

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: