Octop

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

📌 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

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

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