Octos 🐙

Like an octopus — 9 brains (1 central + 8 in the arms, one per arm). Every arm thinks independently, but they share one brain.

Open Cognitive Tasks Orchestration System — a Rust-native, API-first Agentic OS.

31MB static binary. ~140 REST endpoints. 15 LLM providers. 14 messaging channels. Multi-tenant. Zero external runtime services.

What is Octos?

Octos is an open-source AI agent platform that lets you run your own AI system on a single machine or across a cloud-and-device pair. You deploy one Rust binary, connect your LLM provider and channels, and Octos handles routing, sessions, tools, memory, and multi-user isolation through a web dashboard and REST API.

You can think of it as the backend operating system for AI agents. Instead of building a new chatbot stack for every use case, you configure Octos profiles with their own prompts, models, tools, and channels, then manage them from one control plane.

The important part for new users is that Octos can be used in three distinct ways:

1. Octos Cloud signup — the easiest path; create an account, choose a node name, and run the generated setup command on your device.
2. Self-hosted local — run Octos only on your own machine or local network.
3. Self-hosted cloud + tenant pair — run your own public VPS plus your own tenant device for internet-accessible remote use.

Why Octos

Most agentic systems are single-tenant chat assistants — one user, one model, one conversation at a time. Octos is different:

• API-first Agentic OS: ~140 REST endpoints (chat, sessions, admin, profiles, skills, swarm, pipeline, metrics, webhooks, SSE). Any frontend — web, mobile, CLI, CI/CD — can be built on top.
• Multi-tenant by design: One 31MB binary serves 200+ profiles on a 16GB machine. Each profile is a separate OS process with isolated memory, sessions, and data. Family Plan sub-accounts.
• Multi-LLM DOT pipelines: Define workflows as DOT graphs. Per-node model selection. Dynamic parallel fan-out spawns N concurrent workers at runtime, with bounded concurrency for fleet stability.
• Swarm dispatcher: Fan contracts to N sub-agents, aggregate artifacts, gate through validator, roll up cost — wired into /api/swarm/dispatch.
• 3-layer provider failover: RetryProvider → ProviderChain → AdaptiveRouter. Hedge racing, lane scoring, circuit breakers.
• LRU tool deferral: ~15 active tools for fast LLM reasoning, ~50 on demand. Idle tools auto-evict. spawn_only tools auto-redirect to background execution.
• 5 queue modes per session: Followup, Collect, Steer, Interrupt, Speculative — users control agent concurrency via /queue.
• Session control in any channel: /new, /s <name>, /sessions, /back — works in Telegram, Discord, Slack, WhatsApp, Matrix, Feishu.
• Sticky thread_id + committed_seq: Every SSE event is bound to a thread; replay is deterministic by committed sequence number (M8.10).
• 3-layer memory: Long-term (entity bank, auto-injected), episodic (task outcomes in redb), session (JSONL + LLM compaction, three-tier).
• Native office suite: PPTX/DOCX/XLSX via pure Rust (zip + quick-xml).
• Sandbox isolation: bwrap + sandbox-exec + Docker + Windows AppContainer. deny(unsafe_code) workspace-wide. 67 prompt injection tests.

Choose a setup path

All three paths are valid. The easiest is Octos Cloud signup, but the self-hosted modes are first-class as well.

Option	Machines involved	Public internet access	Who manages the infrastructure	Best fit
1. Octos Cloud signup	Your device + Octos Cloud	Yes	Octos Cloud + you	Fastest path
2. Self-hosted local-only	One machine	No	You	Local/private use
3. Self-hosted cloud + tenant pair	Your VPS + your device	Yes	You	Full self-hosting with remote access

Visual overview:

Option 1: Sign up on Octos Cloud

This is the easiest way to get started.

1. Go to the Octos Cloud signup page.
2. Register with your email.
3. Choose a custom node name.
4. Run the generated setup command on your device.

That setup command is personalized for your machine and includes the values needed to connect your device to the Octos cloud relay. After setup, your Octos instance is accessible on the public internet under your node name.

When you click Send Code on the portal, check your Spam folder if the email does not arrive right away. It is also a good idea to add the Octos sending domain/address to your address book so future login and setup emails are delivered reliably.

After signup, the portal shows your node details, public URL, and the setup command to run on your device:

This path is the best choice if you want:

• the fastest time to first working system
• public access without running your own VPS
• a hosted signup and tunnel flow

Option 2: Self-hosted local-only

Choose this if you want Octos on your own machine with no public exposure. Your dashboard is available only on the machine itself or your local network.

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

# Windows (PowerShell)
irm https://github.com/octos-org/octos/releases/latest/download/install.ps1 | iex

This installs the binary, sets up octos serve as a service, and starts the local dashboard at http://localhost:8080/admin/. The end-user web app is served same-origin at http://localhost:8080/app/ (embedded in the binary — no separate web server needed).

Alternatively, install just the binaries (the octos server plus its bundled skills) via a package manager:

# Homebrew (macOS Apple Silicon, Linux x86_64/ARM64)
brew install octos-org/tap/octos

# npm (macOS Apple Silicon, Linux x86_64/ARM64, Windows x64)
npm install -g @octos-org/octos

Both install the full release bundle — the octos server and its bundled skills (news_fetch, deep-search, deep_crawl, send_email, account_manager, voice, clock, weather) kept side-by-side so octos serve discovers them at startup. Unlike install.sh, they do not set up a background service; run octos serve yourself.

Supported platforms: macOS ARM64, Linux x86_64, Linux ARM64, and Windows x64.

Choose this path if you want:

• the simplest self-hosted setup
• one machine only
• local-network access only
• the option to upgrade later to tenant mode

Option 3: Self-hosted cloud + tenant pair

Choose this if you want full self-hosting but still want your own device accessible from anywhere on the public internet.

This mode uses two machines:

• a cloud VPS that runs the public relay and HTTPS entrypoint
• your tenant device that runs your own Octos instance

The tenant device connects outbound to the VPS using frpc. The VPS runs the public components, including TLS and routing. This gives you ngrok-style public access, but through your own infrastructure.

For production use, the VPS also needs wildcard HTTPS. The current setup uses Caddy plus Cloudflare DNS challenge, or another supported DNS provider, to issue and manage certificates for the main domain and tenant subdomains.

Requirements for this option:

1. Your own hosted domain name Example: octos.example.com
2. A DNS provider / authoritative DNS API Its role here is specifically the ACME DNS-01 solver used by Caddy's internal ACME client to mint the wildcard certificate for *.octos.example.com, which is what tenant subdomains use. If you stay HTTP-only with --http-only, or if you only need the apex domain, this wildcard-DNS flow is not required.
3. An SMTP service This is needed so the cloud host can send OTP emails to tenants during portal signup and login.

1. Bootstrap the VPS

On a Linux VPS with DNS already pointed at it, you can either:

• run the script with full flags for a mostly non-interactive flow, or
• run bash scripts/cloud-host-deploy.sh with no flags and let it prompt you interactively

Before running it, export the environment variables needed by your chosen providers. For example:

export CF_API_TOKEN=xxx
export SMTP_PASSWORD=xxx

Notes:

• For Cloudflare, the script expects CF_API_TOKEN for the DNS provider token.
• For SMTP, you can pre-export SMTP_PASSWORD so the bootstrap does not need that secret entered later.
• If you enable SMTP, the script will also prompt for or use the rest of the SMTP settings such as host, port, username, and from-address.

Example using explicit flags:

git clone https://github.com/octos-org/octos.git
cd octos
bash scripts/cloud-host-deploy.sh \
    --domain octos.example.com \
    --https --dns-provider cloudflare

Interactive mode:

git clone https://github.com/octos-org/octos.git
cd octos
bash scripts/cloud-host-deploy.sh

This wraps three host-side steps:

• scripts/install.sh — installs octos serve and sets mode = "cloud"
• scripts/frp/setup-frps.sh — installs and configures frps
• scripts/frp/setup-caddy.sh — configures public routing and wildcard HTTPS

Windows Server targets use the PowerShell deploy script from an operator machine with OpenSSH access to the server:

.\scripts\deploy.ps1 `
    -HostName win.example.com `
    -User Administrator `
    -Version latest `
    -RemoteRoot 'C:\octos' `
    -ServiceName OctosServe

Run the same command with -DryRun first to print the remote commands without connecting. The script deploys the octos-bundle-x86_64-pc-windows-msvc.zip release bundle, installs octos.exe under C:\octos\bin, stores runtime data in C:\octos\data, writes logs under C:\octos\logs, and registers OctosServe as an auto-start Windows service through NSSM. Use -LocalBundle <zip> to deploy a locally built bundle over scp, and -Uninstall [-Purge] to remove the service and optionally delete the remote install root.

Recommended DNS split:

• octos.example.com and *.octos.example.com for the portal and tenant dashboards
• frps.octos.example.com as DNS only so tenant machines can reach the FRP control port

2. Register or create a tenant

Once the VPS is up, the cloud host can issue a personalized tenant setup command. That command includes the tenant name, per-tenant tunnel token, SSH port, dashboard auth token, domain, and relay address. The user receives this command directly in the portal and also by email.

3. Run the tenant setup command on your own device

Use the exact command provided in step 2. The example below is reference only, to show what kind of command the portal issues:

curl -fsSL https://github.com/octos-org/octos/releases/latest/download/install.sh | bash -s -- \
    --tunnel \
    --tenant-name alice \
    --frps-token <per-tenant-uuid> \
    --ssh-port 6001 \
    --domain octos.example.com \
    --frps-server frps.octos.example.com \
    --auth-token <dashboard-token>

The installer writes the tenant tunnel configuration, installs frpc, and starts the public tunnel alongside octos serve.

Can I start local and upgrade later?

Yes.

A local-only self-hosted machine can be upgraded later to tenant mode once you have a cloud host available. The saved installers support this directly:

# macOS / Linux
~/.octos/bin/install.sh --tunnel
~/.octos/bin/install.sh --doctor

# Windows
& "$HOME\.octos\bin\install.ps1" -Tunnel
& "$HOME\.octos\bin\install.ps1" -Doctor

That upgrade path is intentional: start with one machine, then add a VPS only when you need internet-facing access.

Optional self-hosted features

# Auto-install runtime dependencies (git, node, python, ffmpeg, chromium)
curl ... | bash -s -- --install-deps

# Set up Caddy reverse proxy with HTTPS for self-hosted local deployments
curl ... | bash -s -- --caddy-domain crew.example.com

Uninstall

Use the matching uninstall flag on the machine you want to remove:

# Tenant or local machine (macOS / Linux)
~/.octos/bin/install.sh --uninstall

# Tenant or local machine (Windows PowerShell)
& "$HOME\.octos\bin\install.ps1" -Uninstall

# Cloud VPS — removes octos serve, frps, and Caddy
bash scripts/cloud-host-deploy.sh --uninstall

# Cloud VPS + wipe data directory (~/.octos) as well
bash scripts/cloud-host-deploy.sh --uninstall --purge

Where config lives

User config + credentials live outside the install dir so reinstalls/upgrades never touch them:

• macOS + Linux: ~/.config/octos/ (config.json, auth.json) — honours $XDG_CONFIG_HOME
• Windows: %APPDATA%\octos\
• Override: set OCTOS_CONFIG_DIR to put config/auth anywhere
• ~/.octos/ holds only the install + runtime state (binaries, bundled skills, sessions, logs). The installer writes only there.

An existing ~/.octos/config.json from older versions is auto-migrated to ~/.config/octos/ on first run (copied, not moved — the original stays as a backup).

Runtime deployment modes

Octos uses "mode" in config.json (see Where config lives above) to describe how a running node behaves:

• local — standalone machine
• tenant — end-user machine with an optional public tunnel
• cloud — VPS relay with tenant management and public signup

scripts/install.sh and scripts/install.ps1 create local or tenant configs. scripts/cloud-host-deploy.sh creates or updates cloud-host configs with mode = "cloud" plus tunnel_domain and frps_server.

Build from source

For development against an unreleased checkout:

# Build and install. The features below are the canonical default
# (matches scripts/milestone-ci.sh) — `octos serve` requires `api`,
# and the gateway needs the relevant channel feature for each
# transport (telegram, discord, etc.). A bare `cargo install --path
# crates/octos-cli` will give you a binary missing `serve` and
# without channel adapters.
cargo install --path crates/octos-cli \
    --features "api,telegram,discord,dingtalk,whatsapp,feishu,twilio,wecom,wecom-bot"

# Initialize workspace
octos init

# Set API key (any supported provider — auto-detected during install)
export OPENAI_API_KEY=your-key-here    # or ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.

# Interactive chat
octos chat

# Multi-channel gateway
octos gateway

# Web dashboard + REST API
octos serve

For a repo-local tenant deploy (builds from source, sets up the same service + tunnel as install.sh), use scripts/local-tenant-deploy.sh --full.

Iterating on a system-installed octos

cargo install --path crates/octos-cli --features "api,..." only drops a binary into ~/.cargo/bin. It does not rebuild the embedded admin dashboard or touch the service installed by scripts/install.sh (the LaunchDaemon on macOS / systemd unit on Linux runs /usr/local/bin/octos). If you have already run install.sh and want to redeploy local changes, use:

./scripts/build-local-bundle.sh --install           # build + bundle + reinstall
./scripts/build-local-bundle.sh --install --tunnel  # same, with tunnel flags passed through
./scripts/build-local-bundle.sh --skip-dashboard    # only Rust changed, skip npm/vite

What it does:

1. Detects your host triple (mirrors install.sh's platform mapping).
2. Runs scripts/build-dashboard.sh (admin SPA → /admin/) and scripts/build-web-app.sh (the octos-web submodule → /app/) so rust_embed bakes both SPAs into the binary. Skip the dashboard build and /admin/ will 307-loop; skip the web build and /app/ returns web_bundle_missing.
3. Delegates cargo build --release to scripts/milestone-ci.sh release-bundle (single source of truth for FEATURES / SKILL_CRATES).
4. Tars binaries into scripts/octos-bundle-<TRIPLE>.tar.gz, which install.sh auto-detects via file://, skipping the GitHub download.
5. With --install, chains into install.sh — copies binaries to $PREFIX, rewrites the service plist/unit, reloads the daemon.

Use this when:

• You changed Rust or dashboard code and need to see it running under the installed service.
• You want to exercise the full installer flow against a local build.

Skip it when you just need the CLI — cargo install --path crates/octos-cli --features "api,telegram,discord,dingtalk,whatsapp,feishu,twilio,wecom,wecom-bot" is faster. Trim the feature list to only the channels you need (or just api for octos chat + octos serve); leaving api off is what causes octos serve to fail with unrecognized subcommand 'serve'.

Documentation

📖 Full Documentation — installation, configuration, channels, providers, memory, skills, advanced features, and more.

Quick links:

• Installation & Deployment
• Configuration
• LLM Providers & Routing
• Gateway & Channels
• Memory & Skills
• Advanced Features (queue modes, hooks, sandbox, tools)
• CLI Reference
• Skill Development

中文: 中文 README | 用户指南 (doc site)

Architecture

10 octos-* crates + 14 app-skill crates + 1 platform-skill crate (25 workspace members total). The runtime auto-installs only the 9 entries in BUNDLED_APP_SKILLS plus the voice platform-skill — see crates/octos-agent/src/bundled_app_skills.rs.

octos-cli   (CLI entrypoint, REST API server, dashboard, config watcher, wizard)
   │
octos-agent (agent loop, tool registry, MCP, hooks, three-tier compaction,
             profile system, sub-agent output router, task supervisor)
   │
   ├─ octos-bus       (14 channels, sessions w/ sticky thread_id, coalescing, cron)
   ├─ octos-llm       (15 providers, AdaptiveRouter → ProviderChain → RetryProvider)
   ├─ octos-memory    (long-term + episodic + HNSW vector + BM25 hybrid search)
   ├─ octos-pipeline  (DOT-graph workflows, per-node model, bounded fan-out)
   ├─ octos-plugin    (skill manifest, discovery, gating, lifecycle, protocol v2)
   ├─ octos-sandbox   (platform sandbox helper binary)
   ├─ octos-swarm     (PM/swarm dispatcher, ledger, topology, validator gate)
   └─ octos-core      (Task, Message, Error types — no internal deps)

Runtime view:
  octos serve (control plane + dashboard, ~140 REST endpoints)
    ├── Profile A → gateway process (Telegram, WhatsApp)
    ├── Profile B → gateway process (Feishu, Slack, Matrix)
    └── Profile C → gateway process (CLI)
         │
         ├── LLM Provider (Anthropic, OpenAI, Gemini, DeepSeek, Moonshot, …)
         │   └── AdaptiveRouter → ProviderChain → RetryProvider
         ├── Tool Registry (~50 built-in + plugins + 9 app-skills)
         │   └── LRU Deferral (~15 active, activate on demand)
         ├── Pipeline Engine (DOT graphs, per-node model, bounded fan-out)
         ├── Swarm Dispatcher (fan-out → aggregate → validator gate → cost rollup)
         ├── Sandbox (bwrap / sandbox-exec / Docker / AppContainer)
         ├── Session Store (JSONL, LRU cache, three-tier compaction, thread_id)
         ├── Memory (MEMORY.md + entity bank + episodes.redb + HNSW)
         └── Skills (bundled + installable from octos-hub)

License

See LICENSE.