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.

🐾 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

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

1. 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: