Like an octopus — 9 brains (1 central + 8 in each 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. 91 REST endpoints. 15 LLM providers. 14 messaging channels. Multi-tenant. Zero dependencies.

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.

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

• API-first Agentic OS: 91 REST endpoints (chat, sessions, admin, profiles, skills, metrics, webhooks). 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.
• 3-layer provider failover: RetryProvider → ProviderChain → AdaptiveRouter. Hedge racing, Lane scoring, circuit breakers.
• LRU tool deferral: 15 active tools for fast LLM reasoning, 34+ 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.
• 3-layer memory: Long-term (entity bank, auto-injected), episodic (task outcomes in redb), session (JSONL + LLM compaction).
• Native office suite: PPTX/DOCX/XLSX via pure Rust (zip + quick-xml).
• Sandbox isolation: bwrap + sandbox-exec + Docker. deny(unsafe_code) workspace-wide. 67 prompt injection tests.

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

Visual overview:

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

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/.

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

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.

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

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

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.

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.

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.

# 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

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

Octos uses "mode" in ~/.octos/config.json 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.

For development against an unreleased checkout:

# Build and install
cargo install --path crates/octos-cli

# 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.

cargo install --path crates/octos-cli 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 so rust_embed bakes a complete SPA into the binary. Skip this and /admin/ will 307-loop.
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 (octos chat, octos gateway) — cargo install --path crates/octos-cli is faster.

📖 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)

octos serve (control plane + dashboard)
  ├── Profile A → gateway process (Telegram, WhatsApp)
  ├── Profile B → gateway process (Feishu, Slack)
  └── Profile C → gateway process (CLI)
       │
       ├── LLM Provider (Anthropic, OpenAI, Gemini, DeepSeek, ...)
       │   └── AdaptiveRouter → ProviderChain → RetryProvider
       ├── Tool Registry (25 built-in + plugins + 9 app-skills)
       │   └── LRU Deferral (15 active, activate on demand)
       ├── Pipeline Engine (DOT graphs, per-node model, parallel fan-out)
       ├── Session Store (JSONL, LRU cache, LLM compaction)
       ├── Memory (MEMORY.md + entity bank + episodes.redb + HNSW)
       └── Skills (bundled + installable from octos-hub)

See LICENSE.