What Octop Is
Octop is a self-hosted AI assistant from TencentCloud, built for more than one person. One admin, several users, each with their own agents, workspaces, providers and scheduled jobs, all running on hardware you control.
It is MIT licensed, written in Python, and passed 4,000 GitHub stars about two months after the repository was created. Everything lives under ~/.octop/: the database, the secrets, the agent workspaces, the logs.
The feature list is long enough to be suspicious of, and we will get to whether it holds up. But the thing that makes this worth a look is not on the feature list at all. It is the deployment shape.
One Process, Not a Compose File With Five Services
Install a self-hosted AI stack and you usually inherit an architecture. An app container, Redis for the queue, Postgres for state, a separate worker, often a vector database, sometimes a reverse proxy. Five or six services, a compose file, and a support surface where any one of them failing gives you a symptom three layers from the cause.
Octop does not do that. One octop run starts the web dashboard, the CLI backend, every IM channel and the cron scheduler, in a single process, on top of SQLite in WAL mode. PostgreSQL is optional rather than assumed.
The interesting design decision is what replaced the queue. Rather than routing work through Redis or a message broker, every surface (web UI, IM messages, scheduled jobs) goes through one in-process HarnessProcessor. The entire runtime state is rebuilt from the control-plane database on boot, so the process is restart-safe by construction rather than by careful shutdown handling.
The honest trade is that one process means one failure domain and a ceiling on horizontal scale. You cannot put the IM gateway on one box and the agent runtime on another. For a household or a team of five, that ceiling is theoretical and the operational simplicity is real. For fifty concurrent users it would not be.
If you are putting this on a home server, two practical checks before you start. Your upload bandwidth sets whether remote access is usable at all, which a speed test settles in thirty seconds, and if you intend to reach it by hostname rather than IP you will want a DNS lookup to confirm the record actually resolves where you think it does.
Multi-User Is the Actual Differentiator
Plenty of projects will run an LLM chat UI on your own machine. Very few of them have a real concept of more than one person.
Octop is built around it. JWT authentication with an admin role, per-user isolation, and each user getting their own agents, each agent with its own workspace, providers, channels and cron jobs. The framing in the README is a household or a small team rather than an enterprise deployment, and the design matches that: one admin who set it up, several people who just use it.
On top of that sits an expert library, scanned at boot, so you switch specialists per task rather than maintaining one agent with a 3,000-word system prompt trying to be everything. There are also 16 MBTI persona templates with an interactive quiz, which is either a nice touch or a gimmick depending on your tolerance for personality frameworks. The underlying capability, distinct personas per agent, is sound regardless of the packaging.
Memory is handled by harness-memory, with hierarchical recall and full-text search, and it travels with the workspace rather than living in a separate service you have to back up separately.
During setup you will need a JWT secret and an admin password of at least eight characters with letters and digits. A random string generator is a better source for both than something you invent at the keyboard, which is reliably less random than it feels.
Where You Talk to It
The surfaces are the part that will decide whether this fits your life, and they are worth reading carefully because they are regionally skewed.
| Channel | Notes |
|---|---|
| Web dashboard | Enabled by default, at 127.0.0.1:8088 |
| CLI | octop chat, plus admin commands |
| HTTP, SSE, WebSocket | Full programmatic access |
| Feishu | App ID and secret |
| DingTalk | App key and secret |
| Bot AppID and token | |
| WeCom | Corp ID and agent secret |
| Discord | Bot token |
Four of the five IM integrations are Chinese platforms. If you are in North America or Europe, Discord is the only channel on that list you are likely to use, and there is no Slack, Telegram, WhatsApp or Matrix support. That is not a criticism of the project, which was clearly built for the market it came from, but it does change the pitch: for a Western self-hoster this is a dashboard and API product with a Discord bridge, not the omnipresent IM assistant the README describes.
LLM providers are more flexible. OpenAI-compatible APIs, DashScope for Qwen, Ollama for local models, and other presets, configured per agent. Ollama support means the whole stack can run without any external API at all, which is the configuration that makes the privacy argument actually true rather than aspirational.
ACP Goes Both Directions
Agent Client Protocol support is implemented in both directions, which is less common than supporting it at all.
Inbound, your Octop agent becomes an ACP server that external tools drive:
octop acp --agent mainThat exposes your configured agent, with its memory and workspace, to Zed, OpenCode or anything else speaking ACP over stdio.
Outbound, Octop delegates to external coding agents. Built-in runners cover OpenCode, CodeBuddy, Claude Code and Codex. You enable acp_runner per agent and then hand off coding work from a chat, with permission gates in between.
The second direction is the useful one and it reframes what Octop is. It is not trying to be a better coding agent than Claude Code. It is positioning itself as the persistent layer that remembers your context and routes the actual coding to whichever tool is best at it. Your assistant holds the long-running state; the specialist does the work and goes away.
Beyond that there is a knowledge base doing RAG over your own documents, a plugin system, browser automation through headless Chromium, an in-browser terminal with AI assistance, and remote desktop streaming with one-click isolated desktops on headless Linux.
Installing It
You do not need Python installed. The installer uses uv to provision Python 3.12 in an isolated venv under ~/.octop/, and explicitly does not touch system Python.
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash
octop init
octop runoctop init runs an interactive wizard that creates the SQLite database, the JWT secret and your first admin account. octop run brings up everything at http://127.0.0.1:8088. There is octop service start to register it with systemd, launchd or Windows services.
Optional extras install separately, for browser automation (--extras browser, which pulls Playwright Chromium) and Feishu support (--extras channels-feishu).
There are also desktop builds for Windows, macOS and Linux, and FnOS NAS packages in both Docker-backed and native flavours, which is a specific and slightly unusual thing to ship and suggests real NAS users asked for it. Docker Compose is the recommended production path.
If you already manage your own Python, PyPI works and skips the install script entirely:
pip install octopTwo Things to Check Before You Run the Installer
Neither of these is a reason to avoid the project. Both are things I would want to know first.
The install script comes from a raw object storage bucket. Look at that URL again: finnie-1258344699.cos.ap-guangzhou.myqcloud.com. That is a Tencent Cloud Object Storage bucket, not octop.cloud and not github.com. You are piping the contents of an anonymous-looking bucket path straight into bash.
It is presumably their bucket. But a bucket name is not a verifiable identity the way a domain with a certificate is, nothing about that hostname ties it to this project, and anyone auditing the command has no easy way to confirm it. Projects that serve installers from their own domain make that check trivial; this does not. If it bothers you, and it reasonably might in a corporate environment, pip install octop avoids the question entirely, or download the script and read it before running it.
Check what you are exposing before you open it up. The defaults are sensible: it binds to 127.0.0.1 and the docs walk you through creating a real password. The moment you run octop run --host 0.0.0.0 to reach it from your phone, you have published a multi-user AI system with shell access, browser automation and remote desktop streaming onto whatever network that interface touches.
Put it behind a VPN or a reverse proxy with TLS, not straight onto the internet. Before and after you change that bind address, an IP check tells you what address the outside world actually sees you on, which is worth knowing precisely when you are about to make a service reachable.
The Security Model, and What It Does Not Cover
Credit where it is due: for a project this young, the security thinking is better than average.
- Multi-user isolation through JWT auth, with per-user agents and workspaces.
- Tool approval, so risky tools need an explicit yes.
- Shell command guardrails, with user-editable allow and deny rules under
~/.octop/security/tool_guard/. - PII redaction, applied before data leaves the workspace.
- Pluggable backends, so agent work happens inside a chosen boundary: local disk, a Docker container, PostgreSQL, or COS and S3.
The Docker container backend is the one to actually use if you are letting agents run shell commands. Guardrails are a list of rules, and a list of rules is a thing that can be incomplete. A container is a boundary that does not depend on having anticipated the command.
What none of this covers, and nothing in this category covers yet, is prompt injection. Octop reads web pages through browser automation, ingests your documents into a knowledge base, and receives messages from IM channels. Every one of those is untrusted text arriving at an agent that can run shell commands. Tool approval genuinely helps here, because it puts a human between the injected instruction and the effect, which is exactly why you should resist the urge to turn it off after the twentieth prompt.
Who Should Actually Run This
A good fit if you want several people sharing one self-hosted assistant, you would rather run one process than maintain a six-service compose file, you want per-user agents with persistent memory, and you are comfortable being the person who owns the box.
A bad fit if you want a single-user local chat UI, where Open WebUI or LM Studio are simpler and more mature, or if your IM platform is Slack, Telegram or WhatsApp, none of which are supported.
Wait a while if you need this to be boring and stable. The repository is roughly two months old. The roadmap still has AgentTeams, expert sharing and self-evolution as unchecked boxes, and a project moving this fast will break things between releases. Back up ~/.octop/ with octop backup before every update.
The part worth taking seriously regardless is the architectural argument. Self-hosted software has drifted towards distributed-systems complexity for workloads that do not need it, and a single restart-safe process rebuilding its state from SQLite is a genuinely better answer for a household of five than a broker, a worker pool and a vector database. More projects in this space should make that trade.
