octop 0.8.5

Smarter self-hosted AI assistant for multiple users and agents, built on harness-agent

Changelog

本文件记录项目的所有重要变更。

格式遵循 Keep a Changelog，版本号遵循 语义化版本规范。

Unreleased

[0.8.4] - 2026-07-02

新增

• 新增浏览器录制/回放 API、AI 面板及远程浏览器重构
• 新增记忆便携服务（支持导出/导入/诊断）
• 新增主动关怀（Proactive Care）功能及 UI 配置项

修复

• 修复 gateway 相关问题

变更

• 界面文案优化调整

[0.8.3] - 2026-07-01

新增

• Subagent 库（专家目录）多语言支持：将内嵌专家拆分到 en/ / zh/ 子目录，目录支持按 locale 加载内容，API 根据 Accept-Language / 用户偏好 / 显式参数解析语言，安装接口将对应语言版本写入工作区
• 服务安装支持 user / system 作用域：Linux 使用 systemd --user，macOS 使用 LaunchAgents；octop run 原子写入 config.json，启动失败时返回可操作的 journal / 日志提示
• octop run 持久化配置：配置变更原子写入 ~/.octop/config.json，避免运行中配置丢失
• 记忆 API 与共享客户端：新增 /api/memory/* 路由与跨模块共享 memory client
• 记忆仪表盘标签页：新增 Overview、Library、Journal 等 Memory 仪表盘标签页
• 记忆前端优化：改进记忆相关前端体验
• 记忆 UI 删除引导：提供记忆删除时的可视化引导

变更

• 记忆仪表盘打磨：进一步优化 memory dashboard 的视觉与交互
• 仪表盘依赖升级与引入 vitest：升级 dashboard 依赖，新增 vitest 测试栈
• 设计计划与杂项修复：补充设计计划文档，修复若干杂项

[0.7.4] - 2026-06-30

新增

• 重构网关媒体处理流程，支持 HITL（人机协作）交互，改进上传 API

修复

• 修复终端重连时 stale-handler 竞争条件，改进会话处理
• 修复仪表盘 i18n 辅助类型定义，通过生产构建

[0.7.2] - 2026-06-26

新增

• 在仪表盘顶部栏新增 Beta 标识

变更

• 标准化 Octop 品牌标识，将 harness-im-bridge 引用重命名为 harness-gateway
• 依赖中使用 orcakit-harness-agent PyPI 包名
• 新增 CONTRIBUTING、SECURITY 文档及 Issue 模板，统一 CI 工作流

[0.1.0-dev] - 2026-06-26

新增

• 项目初始化：配置系统、用户管理、数据库层（SQLite + Alembic 迁移）
• Agent 系统：AgentRegistry 全局单例、AgentRuntime 生命周期、工作区管理
• 身份认证：JWT 登录/登出、管理员初始化向导、argon2id 密码加密
• 聊天系统：SSE 流式对话、多会话管理、Agent 分组会话列表
• 频道系统：多渠道支持（回环、WebSocket 等）、QR 扫码接入（飞书/企业微信/微信公众号）
• Cron 任务：全局 CronManager、CronJob 触发器解析、定时任务执行
• Slash 命令：斜杠命令解析器、命令分发器、媒体后端代理
• 技能市场：SkillHub 技能浏览/搜索/安装、排行榜
• 专家模板：MBTI 16 型人格模板、一键创建 Agent、专家管理页面
• 仪表盘：基于 Finnie 的 React 前端、侧边栏 IA 重组、PageShell 统一页面包装
• 设置向导：4 步初始化向导（密码验证、创建管理员、模型配置、自动登录）
• 浏览器自动化：Playwright 远程浏览器会话、多标签页支持、交互式画布
• 终端系统：每 Agent PTY 终端、AI 助手面板、ops-engineer 专家模板
• 存储后端：管理员存储后端配置、存储类型卡片展示
• CLI 工具：完整的子命令集（server/user/agent/chat/channel/cron/provider/admin）
• API 文档：Scalar API 文档界面
• 管理功能：用户管理、审计日志、指标统计、共享模型管理

修复

• 修复浏览器页面容器崩溃问题（添加 --no-sandbox）
• 修复 skillhub 搜索输出解析（移除 --json 标志）
• 修复前端 TypeScript 类型错误
• 修复设置向导本地化命名冲突
• 修复 Agent 工作区初始化顺序

变更

• 基础设施重构：AgentRegistry + Gateway + 全局 CronManager 架构
• 代码重组：core/ → infra/、合并 shared.py、扁平化工具层
• 前端重构：聊天页面消费 Orca SSE 协议、模型选择器移至输入工具栏
• 侧边栏重构：4 组 IA（常用/控制/设置/管理）
• 页面包装：统一 PageShell 页面包装器、RequireAdmin 路由守卫
• 专家页面改造：双标签布局、AgentCard 组件、创建/编辑抽屉
• 频道页面改造：预设卡片网格布局、抽屉式编辑

安全

• 实现 JWT 认证、密码哈希加密、跨用户授权边界测试

0.1.0 - 2026-06-25

新增

• 支持多用户、多 Agent 的自托管 AI 助手 — 更聪明，更懂你
• Web 控制台（React + TypeScript + Vite）、CLI（octop run / octop chat / octop acp）与 HTTP/SSE API
• 基于 harness-agent 的 LangGraph Agent 运行时
• IM 通道集成（飞书、钉钉、QQ、Discord、企业微信等）via harness-gateway
• 内置专家库与 16 种 MBTI 人格模板
• Connector 生态（OAuth、MCP 网关）与可插拔工作区后端（本地 / COS / S3 / Docker）
• ACP 双向集成 — 入站 octop acp 与出站 acp_runner 委派
• 主动定时任务（APScheduler）与自然语言 / 斜杠命令触发
• 首次运行向导（octop init）与 JWT 多用户认证
• Docker 多阶段构建与 docker compose 一键部署
• 添加 MIT License

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

Highlights · Overview · Core Technology · Features · Quick Start · Contents

English · 中文

---

Octop is an open-source AI assistant platform built on the Harness stack — multi-user, multi-agent, fully self-hosted. One process runs the dashboard, CLI, IM channels, and cron jobs; all data stays on your machine.

Chat through the Web Dashboard, Feishu, DingTalk, QQ, Discord, WeCom, or programmatic HTTP/SSE. 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
↔️	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
🏠	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 SQLite database under ~/.octop/.

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.11+
Web framework	FastAPI + uvicorn
Agent runtime	harness-agent
Gateway	harness-gateway
Control plane DB	SQLite (WAL) via aiosqlite
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 — LangGraph-based 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 ~/.octop/octop.db on boot.

🤔 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 API — full programmatic access

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.

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

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

Alternative — PyPI (if you already manage Python yourself):

pip install octop
# optional: pip install "octop[browser]"

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 — default credentials are admin / octop (change immediately).

Docker (recommended for production)

# Build and start
docker compose -f deploy/docker-compose.yml up -d

# Or build manually
bash deploy/docker_build.sh
docker run -d \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  -e OCTOP_DEFAULT_PASSWORD=changeme \
  octop:latest

Open http://localhost:8088 — default credentials are admin / octop (change immediately).

Variable	Default	Description
OCTOP_PORT	8088	HTTP listen port
OCTOP_DEFAULT_PASSWORD	octop	First-run admin password
OCTOP_ADMIN_USERNAME	admin	First-run admin username
OCTOP_DATA	~/.octop	Host data directory (compose bind mount)

See .env.example for the full list.

📑 Contents

• Highlights
• Overview
• Core Technology
• Features
• 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
  • License

📦 Install options

Method	Platform	Description
Remote one-liner	macOS / Linux	curl …/octop/install.sh | bash
Remote one-liner	Windows	irm …/octop/install.ps1 | iex or install.bat
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	deploy/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.

⚙️ 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

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

📖 CLI reference

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 backup	Export / restore backups
octop clean	Remove CLI state or wipe ~/.octop/
octop update	Check for and install updates

Full reference: docs/cli.md.

🖥️ Web dashboard

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

See docs/configuration.md for env vars and config.json.

🏗️ Architecture

OctopServer
 ├─ DBPool               SQLite (WAL mode)
 ├─ SharedServices       DI root — every repo + config
 ├─ ExpertCatalog        scans agents/experts/library/ at boot
 ├─ UserManager
 │   └─ HarnessAgentManager (per user)
 │       └─ AgentRuntime (per agent)
 │           ├─ HarnessAgent      LangGraph 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 ~/.octop/octop.db.

See docs/architecture.md and docs/adr/001-single-process-model.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

deploy/        Docker Compose, entrypoint, build & deploy scripts
tests/         unit/ + integration/

🛠️ Development

Prerequisites: Python 3.11+, Node 18+, uv

# Backend
make install          # pip install -e ".[dev]"
make all              # lint + typecheck + test (ship bar)

# Frontend (separate terminal)
make dev-frontend     # Vite dev server on :5173
make build-frontend   # production build → src/octop/dashboard/
cd dashboard && npx tsc --noEmit

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

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

📄 License

This project is licensed under the MIT License.