Octos review: a Rust agent kernel you self-host, with the browser app built in

Who Octos is for, and the problem it names

The README frames the gap directly: most agentic systems are single-tenant chat assistants, one user, one model, one conversation at a time. Octos is positioned as the opposite. It calls itself a backend operating system for AI agents, and the pitch is that you configure profiles with their own prompts, models, tools and channels, then manage them from one control plane instead of building a new chatbot stack per use case.

That makes the target audience narrower than the word assistant suggests. If you want a chat window, the README points you at octos-web, the browser client, which is a separate repository and a git submodule here. If you want a terminal, it points at octoscode. This repository is the kernel: the agent runtime, LLM providers, tools, sandbox, memory, channels, and the API everything else speaks. The README says to install this first, then live in a client.

The multi-tenant claim is the sharpest part of the positioning. The README states that one 31MB binary serves 200+ profiles on a 16GB machine, and that each profile is a separate OS process with isolated memory, sessions and data. Process-level isolation is a heavier design than sharing one runtime with per-user namespaces, and it is the reason the memory figure is stated per machine rather than per process. Treat the 200+ number as a design target from the README, not a measured ceiling.

How the kernel is put together: crates, ports and the API surface

The workspace in Cargo.toml is the clearest map of the architecture. Alongside octos-core, octos-agent, octos-llm, octos-memory, octos-bus and octos-server, there are crates for sandbox, store, services, workflows, pipeline, plugin, swarm, fleet and fleet-worker. Language bindings get their own members: octos-ffi, octos-uniffi, octos-wasm and octos-pyo3. Skills are crates too, under crates/app-skills and crates/platform-skills, covering news, deep-search, deep-crawl, send-email, account-manager, time, weather, smart-home, wechat-bridge, skill-evolve, voice, and several harness starters.

Two properties stand out. The workspace sets unsafe_code to deny, and the dependency comments show the consequence: the rpassword dependency is there because the workspace ban blocks a hand-rolled termios wrapper for echo-free secret input. That is a real constraint on contributors, not a slogan. The second is the absence of external runtime services. The README claims zero external runtime services, which matches a repository whose only compose services are the binary itself in two modes.

The interface layer is where clients attach. The README describes 80+ REST endpoints across chat, sessions, admin, profiles, skills, swarm, pipeline, metrics and webhooks, plus UI Protocol v1, a JSON-RPC contract over WebSocket and stdio. On top of that sit sticky thread_id and committed_seq: every SSE event is bound to a thread and replay is deterministic by committed sequence number. Deterministic replay is the kind of property you only notice when it is missing, and it is what lets a reconnecting client resume without duplicating or dropping turns.

Install Octos and get a first reply from the agent

The README gives a four-step path for macOS Apple Silicon, Linux x86-64 and arm64, and Windows x64. Homebrew and npm are both offered; the brew tap points at the repository itself.

brew tap octos-org/octos https://github.com/octos-org/octos
brew install octos-org/octos/octos      # or: npm install -g @octos-org/octos

Then choose a provider and a model interactively. The README warns that some providers reject the auto default, so pick a real model name when prompted.

octos init
octos auth login --provider deepseek    # use the provider you chose above

The README notes the credential is stored securely, and that exporting the provider's API key environment variable or adding the key in dashboard settings are alternatives. Then start the server with password-free local sign-in.

octos serve --solo

Open http://localhost:50080, which lands on /app/, click the local sign-in button, and send a message. If nothing answers, the README's troubleshooting table is explicit: the agent does not reply because there is no provider credential yet. An invalid model error means the provider rejected the configured model name, so re-run octos init and choose a real one.

There is a second install path that runs Octos as a background service with auto-start, bundled skills and the dashboard on port 8080. The README gives the curl command and links to the octos-web self-hosting guide for the rest.

curl -fsSL https://github.com/octos-org/octos/releases/latest/download/install.sh | bash

For a source checkout, the Makefile wraps the same flow. make init creates a project-local .octos/config.json, and make serve runs the CLI with the api feature against 127.0.0.1 on port 50080 with --solo. make app-build builds the embedded browser assets, and make dev does both before serving.

The port and credential traps that make Octos look broken

The most common failure is not a crash. It is a blank page or a silent agent, and the README devotes a table to it. Two ports are in play: octos serve --solo uses 50080, while the service installer uses 8080. If you set up one and check the other, the page does not load and nothing in the logs looks wrong. This is a documentation problem as much as a user problem, since the two paths are described in different repositories.

The second trap is the credential. A fresh install with a chosen provider but no login produces an agent that accepts your message and says nothing useful. The README's fix is to run octos auth login --provider <name>, export the provider's API key environment variable, or add the key in dashboard settings. The third trap is the model name: an invalid model error is a provider-side rejection of the configured name, not a network fault, and the remedy is to re-run octos init and pick something real, with deepseek-v4-flash given as an example.

The dashboard at /admin/ adds a fourth: it asks for a login, and the README says to use the Login with admin token tab with the Auth token the installer printed, which is also stored in the service file. That token is documented in the octos-web self-hosting guide, not here. If you never saw the installer output and the service file is gone, this repository does not tell you how to recover it. For diagnosis, octos status shows what is running and octos doctor checks the environment.

Multi-LLM pipelines, swarm dispatch and the limits of the README

The orchestration features are the reason to look past the quick start. Multi-LLM DOT pipelines let you define workflows as DOT graphs with per-node model selection, and dynamic parallel fan-out spawns N concurrent workers at runtime with bounded concurrency. Agent topologies come in three shapes: sub-agents as in-process children you own, peer agents as sovereign sibling sessions via peer_handoff and peer_gather, and a swarm dispatcher that fans contracts to N workers, native or external via claude -p or codex exec, validator-gated with cost rolled up, exposed at /api/swarm/dispatch.

Tool handling is tuned for model latency. The README describes LRU tool deferral keeping roughly 15 tools active and about 50 on demand, with idle tools evicted and spawn_only tools redirected to background execution. Sessions get five queue modes (Followup, Collect, Steer, Interrupt, Speculative) controlled with /queue, and session commands /new, /s, /sessions and /back work across Telegram, Discord, Slack, WhatsApp, DingTalk, Matrix and Feishu. Provider failover runs through three layers: RetryProvider, ProviderChain and AdaptiveRouter, with hedge racing, lane scoring and circuit breakers.

What the README does not give you is operational detail. There is no rollback procedure, no migration guidance between the release candidates, and no sizing table beyond the single 200+ profiles on 16GB claim. The swarm and pipeline sections describe what the endpoints do, not what happens when a validator rejects a contract or when a peer agent never returns. The repository does carry a book/, a specs/ directory, CHANGELOG.md and a docs/ tree, so the depth exists somewhere, but the README alone is not enough to run this in production.

Docker, source builds and what the packaging actually contains

The Dockerfile builds in a rust:1.88-alpine stage with musl-dev, git and pkgconfig, copies the Cargo manifests first to cache dependencies, and creates stub source files so the dependency layer survives source changes. That is a standard Rust build-cache pattern, and it means the first build pulls the whole dependency graph while later ones only recompile Octos crates.

compose.yml defines two profiles rather than two services you run together. The agent profile runs octos chat for one-shot queries, mounting .octos/config.json read-only and a named octos-workspace volume at /root/.octos. The gateway profile runs the long-running bot with restart: unless-stopped and the command gateway.

docker compose --profile agent run --rm octos-agent -m "Hello"
docker compose --profile gateway up -d

Note what the read-only mount implies: the config file is supplied from the host, so provider credentials and profile definitions are managed outside the container. The named volume holds the mutable state. There is also a flake.nix and a nix/ directory for Nix users, a Formula/ directory behind the Homebrew tap, and packaging/ for release artifacts. The workspace targets Rust 1.85.0 and edition 2024, while the Docker builder uses rust:1.88-alpine, so the container toolchain is ahead of the declared minimum.

Alternatives: Octos against a single-tenant coding agent

The honest comparison is with an external CLI agent that Octos already knows how to call. The swarm dispatcher accepts external claude -p or codex exec workers, which tells you the maintainers see those tools as peers rather than rivals. The difference in approach is where state and control live. A CLI coding agent runs one session in your terminal, owns its own context, and stops when you close it. Octos runs a server that owns sessions, memory, profiles and channels, and the CLI becomes one client among several.

That trade is not free. A CLI agent needs no port, no admin token, no provider login step inside a running service, and no decision about which of two ports your install uses. Octos needs all four before the first reply. What you get in return is multi-tenant isolation, deterministic SSE replay keyed to committed_seq, provider failover across three layers, and the ability to reach the same agent from Telegram or Feishu. If your problem is one developer and one repository, the CLI is less machinery for the same result. If your problem is many users or many profiles behind one control plane, the CLI has no answer at all.

Licence, release cadence and upgrade cost

Octos is Apache-2.0, declared in the workspace package metadata and shipped as a LICENSE file at the repository root. Apache-2.0 is permissive and includes an explicit patent grant, which matters if you embed the binary in a commercial product. It also means there is no copyleft obligation on your own code. This is a description of the licence text, not legal advice; if you redistribute Octos or modify it, read the LICENSE and NOTICE handling yourself.

The upgrade picture is the part to weigh carefully. The three most recent releases are v2.0.3-rc.9, v2.0.3-rc.8 and v2.0.3-rc.5, all release candidates, and the workspace version in Cargo.toml is already 2.0.3-rc.11. The last push to the default branch was on 2026-08-23. So the project is moving, but the published artifacts are pre-release builds, and the version in the tree is ahead of the newest tagged release. If you pin to a release candidate, expect to move again when the next one lands.

Upgrade cost is dominated by the model name. Because providers reject unknown model identifiers and the README tells you to re-run octos init when that happens, a provider deprecating a model turns into a configuration change on your side. There is no documented migration path between release candidates, and no rollback instructions in the README. Check CHANGELOG.md and cliff.toml, which indicates automated changelog generation, before you move a running deployment.

Editorial conclusion

Adopt Octos if you want an agent runtime you host yourself and you are comfortable picking a provider, a model name, and a port before anything works. Do not adopt it if you want a finished chat product out of the box, or if you cannot accept release candidates as your upgrade path. Before committing, run octos doctor, confirm which port your setup actually uses (50080 for octos serve --solo, 8080 for the service installer), and read the octos-web self-hosting guide, because the admin token and dashboard login live there, not in this repository.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes