更智能的私有化 AI 助手 —— 多用户、多 Agent 架构。

亮点特性 · 概览 · 核心技术 · 功能特性 · 路线图 · 快速上手 · 目录

English · 中文

---

Octop 是一款开源的私有化 AI 助手。它不仅是一个工具，更是可以并行运转的数字化生命体。通过其多 Agent 架构，Octop 为团队、家庭和个人构建了一个既能独立运作又能高度协同的智能环境。最重要的是，它完全运行在你的本地机器上 —— 纯私有化设计意味着数据隐私零妥协，而单进程启动机制则让强大的 Web 控制台、CLI 及主流即时通讯（IM）集成触手可及。

你可以通过 Web 控制台、飞书、钉钉、QQ、Discord、企业微信，或通过编程式 HTTP/SSE/WebSocket 接口与它对话。借助专家库、**连接器（Connectors，支持 OAuth + MCP）**以及面向 IDE 工作流的 ACP 集成，你可以轻松扩展它的各项能力。

特性	说明
👥	多用户专家团队
🎭	MBTI 人格面具
🔒	内置企业级安全
🔌	连接器生态
💾	可插拔后端存储
🧠	可迁移记忆系统
📚	私有知识库
🧩	插件扩展机制
↔️	ACP 双向协议
💻	Terminal AI+
🌐	Browser AI+
🖥️	远程桌面
🏠	完全私有化部署

Octop 是一款面向家庭和小型团队的私有化部署 AI 助手平台。它通过单一进程同时提供 Web 控制台、CLI、IM 渠道接入（飞书、钉钉、QQ、Discord、企业微信等）以及 Cron 定时自动化任务 —— 所有组件共享 ~/.octop/ 目录下的统一控制面数据库（默认 SQLite，可选 PostgreSQL）。

Octop 的核心设计目标：将所有对话、工作区与访问凭证完整保留在用户的本地机器上，同时赋予每位用户一支专属的特化 Agent 专家团队，支持根据任务随时切换。

🐾 使用 Octop 你可以做什么

• 个人助理 —— 让专属 Agent 帮你撰写周报、整理笔记以及管理日常日程；记忆随工作区持久化留存。
• 全家共享 —— 只需一个管理员账户即可覆盖整个家庭；为每位家庭成员分配专属的 Agent 与专家角色。
• 团队协同 —— 多个 Agent 并行协作，桥接飞书、钉钉、企业微信等群聊，将任务自动化分发至相应群组。
• 开发者提效 —— 通过 ACP 将编程任务委派给 OpenCode / Claude Code，或在终端中借助 AI 辅助快速排查故障。
• 网页自动化 —— 利用 Browser AI+ 自动完成表单填写、页面截屏及公开信息采集。
• 定时任务管理 —— 使用自然语言配置 Cron 任务，让 Agent 每天按时执行或主动推送提醒。

分层	技术选型
开发语言	Python 3.12+
Web 框架	FastAPI + uvicorn
Agent 运行时	harness-agent
网关组件	harness-gateway
控制面数据库	SQLite（WAL 模式，默认）或 PostgreSQL（可选）
前端技术栈	React 18 + TypeScript + Vite + Ant Design
调度框架	APScheduler
ACP 协议	agent-client-protocol
构建与代码质量	hatchling · ruff · mypy · pytest

Octop 构建在 Harness 技术栈之上 —— 这是一组高度聚焦的独立运行时，由 Octop 统一组合进单一进程中：

• harness-agent —— Agent 核心运行时：负责模型路由、工具调用、技能集编排与对话状态快照管理。
• harness-gateway —— 多平台 IM 渠道接入网关，将各平台传入的消息归一化并投递至统一处理管线。
• harness-memory —— 支持分层召回与全文检索的记忆系统，使 Agent 的长期记忆能够随工作区自由迁移。
• harness-browser —— 基于 CDP（Chrome DevTools Protocol）的浏览器自动化运行时，带持久化配置文件以支持复杂网页任务。

不同于依赖外部消息队列或消息中间件的系统，Octop 通过进程内的 HarnessProcessor 统一路由所有交互界面（Web UI、IM 和 Cron 定时任务）。这种架构造就了一个具备容灾重启能力的单进程系统，启动时能够从控制面数据库完整恢复所有状态（默认本地 SQLite；可选 PostgreSQL）。

• 基于 JWT 的多用户认证体系，包含管理员角色

• 首次运行引导向导（octop init）

• 交互式 API 文档，访问路径 /api/docs（默认关闭 —— 可在 config.json 中配置 "enable_api_docs": true 启用）

• 每个用户支持创建多个 Agent；每个 Agent 拥有独立的工作区、模型提供商、通知渠道和定时任务

• 内置 16 种 MBTI 人格模版，支持自定义 System Prompt

• 启动时自动扫描专家库（infra/agents/experts/library/）

• 灵活的工作区存储后端：支持本地磁盘、腾讯云 COS、AWS S3 及其他远程存储

• 深度集成即时通讯（IM）渠道：飞书、钉钉、QQ、Discord、企业微信等

• 主动式 Cron 定时任务，支持自然语言与斜杠命令（slash-command）触发

• 跨 Web UI、IM 渠道与 Cron 触发面的统一消息处理核心

• Web 控制台 —— 对话、Agent 管理、连接器配置、渠道接入、Cron 管理及系统设置

• CLI —— octop run、octop chat、octop acp 以及多项管理命令

• HTTP / SSE / WebSocket API —— 完备的编程式接入能力

• 私有知识库 —— 基于本地文档的 RAG 检索增强生成；上传文件后通过语义检索将 Agent 答复锚定在私有语料库中

• 插件系统 —— 安装和管理第三方插件（octop plugin）；内置插件已预置就绪，可在控制台随时按需开启或停用

ACP（Agent Client Protocol，智能体客户端协议）

Octop 提供了双向 ACP 协议支持：

1. 入站（Inbound） —— 外部开发工具调用你的 Octop Agent：

   bash octop acp --agent main # 面向 Zed、OpenCode 等工具的 stdio ACP 服务端

2. 出站（Outbound） —— Octop 将任务委派给外部编程智能体：

   • 打开控制台 → ACP（/acp）：配置运行器 Runner（用户维度全局生效）
   • 在对应的 Agent 中启用 acp_runner，随后即可在聊天窗口中发起任务委派

内置的出站运行器（Runners）涵盖 OpenCode、CodeBuddy、Claude Code 以及 Codex。

完整配置指南参见：docs/acp.md。

以下是团队的中长期演进规划：

该路线图将随社区反馈和发展动态调整；仅供参考。

• 支持操作系统：macOS / Linux / Windows
• 无需预装 Python —— 安装程序使用 uv 在 ~/.octop/ 目录下独立配置隔离的 Python 3.12 虚拟环境
• 硬件配置建议：现代多核 CPU，预留数 GB 内存供主进程及模型/Embedding 缓存使用；预留充足磁盘空间存放数据库、Agent 工作区与文档知识库

macOS / Linux —— 一键安装脚本（推荐）：

bash curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash

Windows (PowerShell)：

powershell irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iex

Windows (cmd) —— 下载并执行，或克隆仓库后运行：

cmd curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.bat -o install.bat install.bat

安装完成后，请打开新终端窗口或重新加载 Shell 环境变量：

bash source ~/.zshrc # Zsh

或

source ~/.bashrc # Bash

安装程序会自动将 octop 放置在 PATH 路径下（路径为 ~/.octop/bin）。可选功能扩展包安装方式：

bash

浏览器自动化支持（Playwright Chromium）

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras browser

飞书渠道支持

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras channels-feishu

完整安装参数配置（如 --version、--from-source、--mirror 以及 Windows 专有标志）请查阅 scripts/README.md。

桌面客户端（GUI 图形界面，无需终端）—— 请直接从 GitHub Releases 下载对应平台的安装包：

平台	安装包产物
Windows	Octop-desktop-windows-amd64-<version>.exe (64 位) / Octop-desktop-windows-arm64-<version>.exe (ARM64) — NSIS 安装程序
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
飞牛 NAS (FnOS)	Octop-fnos-docker-<version>.fpk (Docker 版) / Octop-fnos-native-<version>.fpk (原生免 Docker 版) — 通过应用中心安装

桌面外壳程序细节详见 desktop/README.md，飞牛私有云打包说明参见 fnos/README.md。

其他安装方式 —— PyPI（适用于自行管理 Python 环境的开发者）：

bash pip install octop

可选：安装浏览器自动化扩展

pip install "octop[browser]"

可选：安装本地 ONNX Embedding 模型缓存支持（模型设置 → 本地）：

pip install "octop[local-embedding]"

该选项会将目录权重下载至 ~/.octop/embedding_models；仅用于嵌入检索，不用于聊天模型与记忆存储。

基于 uv 从源码检出构建：

bash uv sync --extra local-embedding

交互式向导会在 ~/.octop/ 目录下自动创建 SQLite 数据库、JWT 密钥以及首个管理员账户：

bash

前台运行（API + Web 控制台）

octop run

指定主机地址与端口

octop run --host 0.0.0.0 --port 8088

注册为系统守护服务（支持 systemd / launchd / Windows service）

octop service start

启动后在浏览器访问 http://127.0.0.1:8088。在使用 Docker 时，若未预先配置 OCTOP_DEFAULT_PASSWORD，系统将在首次初始化时生成高强度随机管理员密码并写入 /data/.octop/credential.txt。使用交互式 octop init 或初始化向导时，系统会提示你手动设置管理员密码（长度需 ≥8 位，且必须包含字母与数字）。

Docker 部署（生产环境推荐）

bash

构建并启动服务

docker compose -f docker/docker-compose.yml up -d

或手动构建镜像并运行

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

在浏览器中打开 http://localhost:8088。首次启动会自动创建管理员账户并将凭据写入容器内的 /data/.octop/credential.txt 文件中。若未设置 OCTOP_DEFAULT_PASSWORD，程序将自动生成强随机密码；若手动设置密码，密码长度必须 ≥8 位且包含字母与数字（弱密码或常见常用密码将被应用安全策略拒绝，并自动回退为生成强随机密码）。

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

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

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

• 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)

• 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

• 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

• 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 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

   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.

Here are our mid-to-long term plans:

This roadmap may shift as the community grows; treat it as indicative only.

• 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

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

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

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.

Variable	Default	Description
OCTOP_PORT	8088	HTTP listen port
OCTOP_DEFAULT_PASSWORD	(unset)	First-run admin password (Docker bootstrap). Unset = random password written to credential.txt
OCTOP_ADMIN_USERNAME	admin	First-run admin username
OCTOP_DATA	~/.octop	Host data directory (compose bind mount)

See .env.example for the full list.

Method	Platform	Description
Remote one-liner	macOS / Linux	`curl …/octop/install.sh
Remote one-liner	Windows	`irm …/octop/install.ps1
Local script	macOS / Linux	bash scripts/install.sh
Local script	Windows	scripts\install.bat or install.ps1
PyPI	Any	pip install octop or pip install "octop[browser]"
Docker	Any	docker/docker-compose.yml

All install scripts provision an isolated environment at ~/.octop/venv and a ~/.octop/bin/octop wrapper — they do not touch system Python.

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.

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

OpenAI-compatible APIs, DashScope (Qwen), Ollama, and other presets — configure per agent in the dashboard or via octop provider.

Channel	Credentials
Feishu	App ID, App Secret
DingTalk	App Key, App Secret
QQ	Bot AppID, Token
Discord	Bot Token
WeCom	Corp ID, Agent Secret
Web Dashboard	Enabled by default
Command	Description
---	---
octop init	Bootstrap ~/.octop/ (DB, admin, JWT secret)
octop run	Start Octop in the foreground
octop service start	Install and start as a system service
octop service stop	Stop the system service
octop agent	Create, list, start/stop agents
octop channel	Install and manage IM channels
octop chats	REPL and session management
octop acp	Stdio ACP server for IDE integration
octop cron	Manage scheduled tasks
octop models	Provider presets and model resolution
octop skills	Enable/disable per-agent skills
octop plugin	Install and manage third-party plugins
octop backup	Export / restore backups
octop clean	Remove CLI state or wipe ~/.octop/
octop update	Check for and install updates

Full reference: docs/cli.md.

After octop run, open http://127.0.0.1:8088.

• Chat — real-time conversation with agents
• Agents — create agents, pick experts / MBTI personas, configure providers
• Connectors — OAuth apps and MCP gateways
• Channels — IM platform setup
• Cron — visual cron job management
• Knowledge base — manage document corpora and semantic retrieval
• Plugins — install, enable, and configure plugins
• 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)

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

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 (harness-agent)
 │           ├─ HarnessProcessor  IM / UI / cron entry point
 │           ├─ ChannelManager    IM connections (harness-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.

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/

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 --noEmit

Individual targets: make test, make lint, make typecheck, make format.

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

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.

See CHANGELOG.md for release history.

Project	Description
harness-agent	Agent runtime — model routing, tools, skills, checkpointing
harness-gateway	Multi-platform IM channel bridge
harness-memory	Hierarchical recall and FTS search
harness-browser	CDP browser automation with persistent profiles

These harness-* projects are being prepared for open-sourcing; repository links will be added once they are published.

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

This project is licensed under the MIT License.

Thanks to all contributors: