MCPcopy Create free account
hub / github.com/TencentCloud/Octop

github.com/TencentCloud/Octop @v1.0.1

Chat with this repo
repository ↗ · DeepWiki ↗ · release v1.0.1 ↗ · + Follow
14,480 symbols 64,912 edges 1,905 files ⚖ MIT 2,537 documented · 18% ● updated 44d agov1.0.2b6 · 2026-10-04★ 6,786388 open issues

Browse by type

⨍ Functions 12,485◇ Types & classes 1,527↳ Endpoints 468
What it actually does AI analysis from the code graph
loading…
README

Octop Banner

A smarter, self-hosted AI assistant — multi-user, multi-agent.

TencentCloud/Octop | Trendshift

Python 3.12+ License: MIT Version PyPI Code Style: Ruff GitHub stars GitHub forks Discord

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.

✨ Highlights

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/

📌 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, 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.
  • Team helper — multiple agents collaborate in parallel, bridging Feishu / DingTalk / WeCom 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+ to fill forms, capture screenshots, and gather public info.
  • 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 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:

  • harness-agent — Agent runtime: model routing, tools, skills, and conversation checkpointing.
  • harness-gateway — multi-platform IM channel bridge that normalizes incoming messages into a single processing pipeline.
  • harness-memory — hierarchical recall with full-text search, so an agent's memory travels with its workspace.
  • harness-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)

Agents

  • Multiple agents 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/)
  • Workspace backends: local disk, COS, S3, and other remote stores

Channels & automation

  • IM channels: Feishu, DingTalk, QQ, 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, agents, connectors, channels, cron, settings
  • CLI — octop run, octop chat, octop acp, admin commands
  • HTTP/SSE/WebSocket API — full programmatic access

Knowledge & plugins

  • Knowledge base — RAG over your documents; upload files and let semantic retrieval ground agent answers in your private corpus
  • 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 bash octop acp --agent main # stdio ACP server for Zed, OpenCode, …

  2. Outbound — Octop delegates to external coding agents

  3. Dashboard → ACP (/acp): configure runners (global per user)
  4. 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:

  • [ ] 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.
  • [ ] Browser & terminal polishing — browser skill recording (capture a workflow and replay it as a skill) and a more capable terminal AI assistant.
  • [ ] AgentTeams — let one coordinator autonomously schedule and orchestrate multiple experts to tackle multi-step tasks.
  • [ ] Self-evolution — automatically distill everyday conversations into reusable skills, so the assistant grows with you.
  • [ ] PC / mobile clients — native desktop and mobile apps alongside the web dashboard and IM channels.

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:

# 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

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/commo

Extension points exported contracts — how you extend this code

browse all types & interfaces →

Core symbols most depended-on inside this repo

browse all functions →

Shape

Function 10,639
Method 1,846
Interface 850
Class 669
Route 468
Struct 7
TypeAlias 1

Languages

Python73%
TypeScript26%
Go1%

Modules by API surface

src/octop/infra/agents/manager.py137 symbols
tests/unit/test_connectors.py102 symbols
src/octop/infra/agents/experts/library/clinical-learning-subscription/scripts/clinical_profile.py90 symbols
dashboard/src/pages/Chat/hooks/chatStore.ts89 symbols
tests/unit/agents/test_agent_manager.py87 symbols
src/octop/api/routers/connectors.py84 symbols
src/octop/api/routers/skills.py73 symbols
src/octop/api/routers/knowledge_bases.py72 symbols
tests/unit/agents/test_agent_registry.py71 symbols
src/octop/infra/skills/skills_hub.py70 symbols
src/octop/infra/agents/experts/skillhub_market.py68 symbols
src/octop/infra/desktop/setup.py67 symbols

Dependencies from manifests, versioned

github.com/adrg/xdgv0.5.3 · 1×
github.com/jchv/go-winloaderv0.0.0-2025040616330 · 1×
github.com/wailsapp/wails/v3v3.0.0-beta.13 · 1×
golang.org/x/sysv0.46.0 · 1×
@aiden0z/pptx-renderer1.2.4 · 1×
@eslint/js9.25.0 · 1×
@mermaid-js/parser1.1.0 · 1×

Datastores touched

octopDatabase · 1 repos
(mongodb)Database · 1 repos
(mysql)Database · 1 repos
octop_testDatabase · 1 repos
ticketsDatabase · 1 repos
dbDatabase · 1 repos
mydbDatabase · 1 repos

For agents

$ claude mcp add Octop \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

Ask about this repo answers extend the page