octop 0.9.4

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

Changelog

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

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

[0.9.4] - 2026-07-11

新增

• 新增 agent backend 的主机 root_dir 浏览器与权限探测能力
• 改进聊天流式滚动行为与思考计时器

修复

• 修复 Windows 下 sqlite 路径测试、媒体路径与 POSIX 专属测试导致的 CI 失败
• 修复 Windows 测试收集问题（惰性导入 pwd 模块）
• 修复 harness-memory Bridge 导入路径
• 修复 CI 流水线并让测试套件通过，项目重命名为 Octop

变更

• Windows 兼容：默认 agent backend 限定到 workspace，并集中 POSIX 专属 stdlib 调用以适配 Windows mypy CI

[0.9.1] - 2026-07-08

新增

• 远程浏览器控制页面与浏览器 AI 面板，支持远程浏览器自动化操作
• 附件下载的 Content-Disposition 头（RFC 5987，兼容非 ASCII 文件名）
• 前端 UI 语言偏好持久化（自动检测浏览器语言并记忆）
• 专家目录欢迎语（默认欢迎内容 / 工作区清单读取 / 专家目录播种）
• 附件相关国际化域（i18n/domains/attachment.py）
• 聊天欢迎语支持

变更

• 重构聊天附件与上传处理链路，精简接口与实现
• 重构网关媒体层：附件提示、入站存储、工具媒体展示重写
• 重构 harness 请求构造与消息处理器
• 调整上下文拆分、专家目录、provider 存储与 agent 管理器
• 重构前端聊天界面：输入框、消息气泡、工具媒体条、上下文窗口环等组件大量更新
• 更新登录、初始化向导、终端 AI 面板等前端页面

修复

• 修复附件路径解析与内容分发相关问题

移除

• 移除模型配置提示弹窗、旧聊天流模块、slash 上下文与附件签名测试

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

Highlights · Overview · Core Technology · Features · 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. 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 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=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	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.

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

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

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

📄 License

This project is licensed under the MIT License.