Octop Self-Hosted Assistant
A private, multi-user workspace that coordinates specialized AI agents across chat, messaging, automation, and developer tools.
- Source repo
- TencentCloud/Octop
- Stars
- ★ 12k
- Last updated
- 1d ago
- License
- MIT
- Primary language
- Python
- FA score
- 67/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- An individual who wants chats, credentials, and documents on a personally controlled machine can use a dedicated agent for weekly reports, note organization, and workspace-persistent memory.
- Not a fit if
- Teams needing multi-node scaling, HA, or automatic failover
- Users who want zero-config setup without model and channel credentials
- Teams needing native PC/mobile clients or AgentTeams, still roadmap items
- Source review
- 67/100 · Some gaps
What does this agent do, and when should you use it?
Octop is an open-source, self-hosted assistant platform designed for individuals, households, and small teams. A single process combines a FastAPI service, React dashboard, CLI, messaging channels, scheduled jobs, and agent runtimes built from the Harness components. Each user can maintain multiple agents with separate workspaces, model providers, channels, expert or MBTI personas, skills, and cron jobs. Tasks can arrive through the web interface, Feishu, DingTalk, QQ, Discord, WeCom, HTTP, SSE, WebSocket, or bidirectional ACP, with responses returned through the relevant surface. Conversations, credentials, workspaces, and control-plane state live under ~/.octop/ by default; SQLite is the standard database, while PostgreSQL and several local or remote workspace backends are supported. It is a fit for adopters who want private knowledge retrieval and operational automation under one deployment, provided they are prepared to run the service and manage model, channel, and security configuration.
Requests from the Web UI, messaging channels, and cron jobs enter a shared HarnessProcessor and are routed to the appropriate user's AgentRuntime. HarnessAgent handles model routing, tools, skills, and conversation checkpoints; harness-gateway normalizes incoming messages; harness-memory supplies hierarchical recall and full-text search; and harness-browser controls persistent Chromium sessions through CDP. An agent can retrieve uploaded knowledge-base documents, call configured models and Connectors, execute approved tools or shell commands, automate web pages, produce a response, and send it back through the originating interface. The octop acp command exposes an Octop agent as a stdio ACP server for IDE and terminal clients, while outbound ACP can delegate coding work to OpenCode, CodeBuddy, Claude Code, or Codex. On startup, OctopServer reconstructs users, agents, channels, and schedules from SQLite or PostgreSQL, then serves the dashboard and HTTP, SSE, and WebSocket interfaces through FastAPI and uvicorn.
- An individual who wants chats, credentials, and documents on a personally controlled machine can use a dedicated agent for weekly reports, note organization, and workspace-persistent memory.
- A household sharing one self-hosted server can use a single administrator account to manage separate users, agents, experts, and workspaces for each family member.
- A small team working in Feishu, DingTalk, or WeCom can route group conversations into one processing pipeline and assign different specialist agents to different tasks.
- A developer can expose a personal Octop agent to an IDE with octop acp or delegate coding work to OpenCode, Claude Code, CodeBuddy, or Codex.
- A user with repetitive browser work can use Browser AI+ to fill forms, capture screenshots, and collect public information.
- An administrator with recurring workflows can define cron jobs through natural language or slash commands and have agents execute or push results on schedule.
How do you install or deploy this agent?
On macOS or Linux, run: curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash. On Windows PowerShell, run: irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iex. The installer uses uv to provision an isolated Python 3.12 environment under ~/.octop/venv, so a system Python installation is not required; afterward, open a new terminal or reload the shell with source ~/.zshrc or source ~/.bashrc. If Python is already managed locally, use pip install octop, or pip install "octop[browser]" for browser support. Run octop init to create the SQLite database, JWT secret, and first administrator; interactive passwords must be at least eight characters and contain letters and digits. For production container deployment, run docker compose -f docker/docker-compose.yml up -d. Docker bootstrap uses OCTOP_DEFAULT_PASSWORD when supplied, otherwise it generates a password and writes it to /data/.octop/credential.txt. Model providers, messaging channels, and Connectors require their corresponding API or platform credentials.
How do you use this agent?
After initialization, run octop run and open http://127.0.0.1:8088. To listen on a different interface or port, use octop run --host 0.0.0.0 --port 8088. In the dashboard, configure a model provider, create an agent, choose an expert or MBTI persona, and then add Connectors, messaging Channels, a Knowledge base, Plugins, ACP runners, or Cron jobs as needed. CLI operations include octop models, octop provider list, octop channel install, octop skills list --agent main, and octop cron create --help. To expose an agent to an IDE or terminal, run octop acp --agent main. For outbound coding delegation, configure a runner on the dashboard's ACP page and enable acp_runner for the target agent. Programmatic clients can use HTTP, SSE, or WebSocket; API documentation is disabled by default and becomes available at http://127.0.0.1:8088/api/docs after setting "enable_api_docs": true in config.json.
What are this agent's strengths and limitations?
- The dashboard, CLI, messaging bridges, API, and cron scheduler share one process and one processing path, keeping deployment centralized while allowing state reconstruction after restart.
- Multi-user operation is a concrete part of the design: JWT authentication, an administrator role, and per-user agents, workspaces, providers, channels, skills, and schedules are documented.
- The local-first boundary is explicit: configuration, chats, credentials, and workspaces default to ~/.octop/, while SQLite, PostgreSQL, local disk, COS, S3, and Docker-backed options provide deployment flexibility.
- Its interface coverage is broad, combining several messaging platforms, HTTP/SSE/WebSocket, MCP-based Connectors, and both inbound and outbound ACP.
- Knowledge-base RAG, portable workspace memory, browser automation, terminal assistance, plugins, and remote desktop support extend it beyond text-only chat.
- Self-hosting transfers responsibility for upgrades, backups, TLS, credential protection, database care, and network exposure to the adopter.
- Useful operation still depends on configuring an external or local model provider; messaging channels, OAuth Connectors, MCP gateways, and coding runners may each require credentials or additional software.
- The single-process architecture simplifies startup, but the supplied material does not establish multi-node scaling, high availability, an external queue, or automatic failover.
- Browser automation, selected messaging channels, and local embedding models require optional extras or model caches, increasing disk, memory, and environment setup costs.
- AgentTeams, shared resource pools, expert sharing, self-evolution, and native PC or mobile clients remain roadmap items rather than delivered capabilities.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Octop Self-Hosted Assistant This agent | 67 · Some gaps | CLIFree + model costs | ★ 12k | 1d ago | Python | Codex · Claude Code · OpenAI API |
| Rakazo AI Teammates | 63 · Some gaps | Self-hosted serviceFree + model costs | ★ 7.2k | today | TypeScript | — |
| CowAgent | 52 · Major gaps | CLIFree + model costs | ★ 48k | 1d ago | Python | OpenAI API · Claude API |
| Iva Personal Assistant | 85 · Good | Chat botFree + model costs | ★ 285 | 3d ago | TypeScript | ChatGPT · Codex |
How does FollowAgents rate this agent?
Why each dimension lost points
The README specifies per-user agents and workspaces, API documentation disabled by default, tool approval, shell rules, PII redaction, and local credential paths. Workflow permissions are scoped to contents:read/issues:write or release-related writes, providing concrete design evidence for least privilege, confirmation, and sensitive-data handling, but the supplied source does not show the runtime enforcement implementations. Data locations and external LLM, IM, OAuth, MCP, remote-storage, and browser capabilities are disclosed, yet outbound-data boundaries, retention, and redaction exceptions are not fully reconciled with the claim that data stays local. Backup-before-upgrade guidance, random credential generation, and security-reporting channels are useful. Dependency security is thin: many dependencies use broad lower bounds, and no lockfile, artifact verification, or vulnerability scanning evidence is supplied; remote pipe-to-shell installation adds supply-chain exposure. The anti-spam workflow automatically labels, comments on, and closes issues without prior human confirmation, although maintainers can recover them. Repository attribution exists, but the license names only “Octop,” package metadata says “octop contributors,” and publisher identity is explicitly unverified, so provenance is only partial.
The README, pyproject, test configuration, and release workflow are broadly consistent about Python 3.12, version 1.0.0, commands, architecture, and quality tooling. Restart reconstruction, migrations, and test categories are documented. Deductions apply because essential harness components are not yet linked as open repositories and are referenced through minimum-version constraints, while remote installers and services have no demonstrated availability guarantees. Failure-message evidence is sparse: the anti-spam workflow validates manual input and warns on some API failures, and password fallback is explained, but no systematic user-facing error strategy is shown for runtime, connector, model, database, or agent failures.
The source thoroughly identifies individual, household, small-team, and developer scenarios and offers Web, CLI, IM, HTTP/SSE/WebSocket, multiple model providers, storage backends, databases, and installation paths for macOS, Linux, Windows, Docker, desktop, and NAS. Capability boundaries are partly expressed through operator security duties, optional components, disabled-by-default API docs, roadmap items, and external-agent delegation, but platform limitations, offline behavior, and resource requirements remain imprecise. Natural-language, slash-command, cron, IM, and API triggers are described, with asserted approval gates; conflict handling, accidental-trigger protection, cron timezone behavior, and concurrent-entry semantics are not evidenced.
The README has strong navigation and detailed architecture, layout, configuration, CLI, deployment, security, contribution, and documentation references. Installation prerequisites, initialization, upgrades, backups, and platform variants are especially thorough. Naming is mostly stable, but “octop chat” conflicts with the later “octop chats” CLI entry. Examples cover major paths, though no actual FAQ or substantial troubleshooting guide is present. The security policy, best-effort support for older releases, variable roadmap, and basic resource guidance identify some limitations, but risks and constraints for browser control, remote desktop, plugins, and delegated agents remain incomplete. The full MIT text matches package metadata, justifying full license credit. Version metadata, a changelog link, and automatic tagging exist, but the changelog content is absent. SECURITY.md supplies a contact, response targets, and support scope, while contribution paths are documented; the unverified publisher and nonspecific maintainer identity limit maintenance-responsibility credit.
The product combines a dashboard, CLI, IM, APIs, scheduling, knowledge retrieval, memory, plugins, browser automation, and coding-agent delegation, making outputs usable across several real workflows and offering substantial marginal value over a basic chat assistant. Scores are reduced because the source offers mostly feature descriptions rather than representative outputs, end-to-end case studies, or quality measurements. Cost guidance is limited to a multicore CPU, a few gigabytes of memory, storage, and caches; model calls, browser workloads, databases, remote storage, and operational maintenance are not quantified or compared with demonstrated benefits.
Many claims trace to concrete README commands, paths, architecture, and configuration and receive partial corroboration from pyproject versioning, dependencies, entry points, quality tools, test fixtures, and release automation. Full credit is withheld because the supplied files do not contain implementations for isolation, PII redaction, approvals, restart safety, or most advertised capabilities, while the test evidence only shows frontend memory fixtures and environment setup. The roadmap is clearly labeled as tentative and generally separated from current features, but marketing statements such as uncompromised privacy and all-local data do not adequately distinguish the data transmission inherently required by external LLMs, OAuth, IM services, S3/COS, and browser activity.
- Do not directly execute the README's remote COS pipe-to-shell or PowerShell installers. Download, inspect, and verify the scripts first, or prefer an auditable source, PyPI, or Docker build path.
- Before enabling external LLMs, IM, OAuth/MCP, COS/S3, browser automation, remote desktop, or third-party plugins, verify actual outbound data, credential storage, permission scopes, logging, and retention. Self-hosting does not mean every datum remains on the host.
- Before binding beyond localhost, configure TLS and network access controls, rotate JWT and administrator credentials, and review ~/.octop/security/tool_guard/. Keep API documentation disabled unless needed.
- Run octop backup and validate restoration before upgrades or migrations. The material documents backup and automatic migration but provides no recovery-drill evidence.
- Key harness dependencies are not linked to source repositories, and many dependency constraints are broad lower bounds. Generate a lockfile, inspect transitive dependencies and known vulnerabilities, and pin trusted artifacts before production use.
- The anti-spam workflow may falsely close genuine reports from new accounts. Maintainers should monitor the pending-maintainer-review label and maintain an explicit human review and reopening process.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
新增 - PostgreSQL 可存放技能包和知识库。多实例共用定时任务、频道、头像、插件和已发布专家 - Docker 与飞牛增加精简版。存储后端增加火山引擎 TOS - 可预建 LDAP 账号，聊天列表可隐藏任意专家 修复 - 专家工作区落到允许的存储根下。共享连接器只有创建者能改 - 聊天历史不再错序，未答完的提问不会被别的会话接走 - 超长图片先缩小再发送。失效的默认模型会自动换掉 - 升级记忆库：长会话分批提炼，重启后不重跑 - 安装清理不再删掉运行环境。PostgreSQL 上的知识库检索和关怀去重恢复正常 变更 - 升级 octop-harness 至 1.0.7 - 内置专家并入专家市场，安装包不再自带市场目录 Downloads Windows Desktop installer (Recommended) …View on GitHub ↗ -
Release notes excerpt
新增 - 账号支持 TOTP 与 Passkey：二次验证、无密码登录和恢复码 - 新增 ragflow 知识库连接器 修复 - 记住登录会自动续期，改密码会退出其他设备。缺 MFA 表的旧库会自动补齐 - 极简模式里，专家会话超过 10 条可以继续展开。长代码在气泡里换行，已结束的一轮不会在历史加载后再出现一次 - 停用的会话模型回到 Auto。钉钉和微信切换时，草稿与二维码不再串台，登录回调会保留转发端口 - 更早回合生成的文件不会再次发出。对话轨迹记下模型实际收到的系统提示 变更 - 通行密钥登录默认关闭，要在应用设置里打开。修改密码放在「账户安全」里 - 虚拟桌面和系统浏览器默认不启动。未选 MBTI 时显示「未设置」 - 升级 octop-harness 1.0.6 Downloads Windows Desktop installer (Recommended) …View on GitHub ↗ -
Release notes excerpt
新增 - 建用户时可以同时创建一个默认专家。权限按页面 Tab 拆开，也可以按组折叠 - 用户组可以限制技能包、知识库、连接器、模型、存储和专家谁能看见 - 技能包可以共享，并用文件树编辑。创建专家、团队等资源时可以选头像 - 表单和对话可以让 AI 润色。搜索增加 DeepSeek 与元宝，模型支持 OpenAI Responses API 修复 - 云端协同共享后可以直接对话。回复进行中不会被刷新冲掉，也不能删掉这场会话 - 手机截图写到专家自己的工作区。只改定时任务文案时，间隔任务不再重新计时 - 浏览器工作台恢复中文输入。主动关怀等对话安静后再发 - 向导密码随数据目录迁移。Linux 桌面无边框窗口可以拖边缘调整大小 变更 - 云端协同默认打码对端地址和账号。共享来的资源在头像上做标记 - 支持子路径部署。飞牛原生包标记为 x86 安全 - 密钥改为加密保存，旧明文仍能读出。插件上传和解压限制了体积 Downloads Windows Desktop installer (Recommended) …View on GitHub ↗