Octop Self-Hosted Assistant
A private, multi-user workspace that coordinates specialized AI agents across chat, messaging, automation, and developer tools.
Per-dimension scores and reasoning
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.
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.
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 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.