Installation & Deployment

Prerequisites

You also need an API key from at least one supported LLM provider.

Optional Dependencies

Build from Source

git clone https://github.com/octos-org/octos
cd octos

# Recommended: canonical feature set (matches scripts/milestone-ci.sh).
# Includes the REST API + dashboard (`octos serve`) and every messaging
# channel adapter. Build this first if you don't know which features
# you need — it's what release artifacts ship.
cargo install --path crates/octos-cli \
    --features "api,telegram,discord,whatsapp,feishu,twilio,wecom,wecom-bot"

# Minimal: CLI + chat + gateway with CLI channel only.
# This produces a binary that does NOT have `octos serve` (the api
# feature is what registers that subcommand) and that has no
# messaging channel adapters compiled in.
cargo install --path crates/octos-cli

# Trim the feature list to your needs. Available channel features:
#   telegram, discord, slack, whatsapp, feishu, email, wecom, wecom-bot,
#   matrix, qq-bot, twilio, wechat
# Required for `octos serve`: api
# Other features: git (gitoxide), ast (tree-sitter)
# Note: the browser tool (headless Chrome via CDP) is always compiled
# in — there is no `browser` feature.
cargo install --path crates/octos-cli --features "api,telegram,slack"

# Verify
octos --version

Deploy Script

For a streamlined installation, use the deploy script:

# Minimal install (CLI + chat only)
./scripts/local-tenant-deploy.sh --minimal

# Full install (all channels + dashboard + app-skills)
./scripts/local-tenant-deploy.sh --full

# Custom channels
./scripts/local-tenant-deploy.sh --channels telegram,discord,api

Node Name Guidelines

For cloud signup and managed tenant installs, the node name becomes both the tenant id and the public subdomain, for example alice.your-cloud.example.

• Use 1 to 64 characters.
• Allowed characters are lowercase letters, numbers, and hyphens.
• Do not start or end the name with a hyphen.
• Choose something stable and easy to remember, because reinstall, support, and diagnostics may refer to the same node name later.
• Avoid temporary names tied to a one-off machine state if you expect to reuse the same public address.

Platform-Specific Instructions

NixOS

If you use Nix, Octos provides a flake with packages, a development shell, and NixOS / nix-darwin modules. See the Nix page for details.

macOS

# 1. Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# 2. Install optional deps
brew install node ffmpeg poppler
brew install --cask libreoffice

# 3. Clone and deploy
git clone https://github.com/octos-org/octos.git
cd octos
./scripts/local-tenant-deploy.sh --full

# 4. Set API key and run
export ANTHROPIC_API_KEY=sk-ant-...
octos chat

Background service (launchd system daemon):

The deploy script creates /Library/LaunchDaemons/io.octos.serve.plist.

# Start service (requires sudo)
sudo launchctl load /Library/LaunchDaemons/io.octos.serve.plist

# Stop service
sudo launchctl unload /Library/LaunchDaemons/io.octos.serve.plist

# Check status
sudo launchctl print system/io.octos.serve

# View logs
tail -f ~/.octos/serve.log

Linux (Ubuntu/Debian)

# 1. Install system deps
sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev

# 2. Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# 3. Install optional deps
sudo apt install -y nodejs npm ffmpeg poppler-utils

# 4. Clone and deploy
git clone https://github.com/octos-org/octos.git
cd octos
./scripts/local-tenant-deploy.sh --full

# 5. Set API key and run
export ANTHROPIC_API_KEY=sk-ant-...
octos chat

Background service (systemd system unit):

The deploy script creates /etc/systemd/system/octos-serve.service.

# Start service
sudo systemctl start octos-serve

# Enable on boot
sudo systemctl enable octos-serve

# Check status
sudo systemctl status octos-serve

# View logs
sudo journalctl -u octos-serve -f

# Stop service
sudo systemctl stop octos-serve

Linux (Fedora/RHEL)

# System deps
sudo dnf install -y gcc pkg-config openssl-devel

# Then follow Ubuntu steps from step 2 onward

Windows (Native)

Octos builds and runs natively on Windows. Shell commands are executed via cmd /C.

# 1. Install Rust (download rustup-init.exe from https://rustup.rs)
rustup-init.exe

# 2. Clone and build with the canonical feature set
#    (omit features only if you just want `octos chat`; `octos serve`
#    requires the `api` feature).
git clone https://github.com/octos-org/octos.git
cd octos
cargo install --path crates/octos-cli `
    --features "api,telegram,discord,whatsapp,feishu,twilio,wecom,wecom-bot"

# 3. Set API key and run
$env:ANTHROPIC_API_KEY = "sk-ant-..."
octos chat

Windows notes:

• Sandbox is disabled on Windows (no bubblewrap/sandbox-exec equivalent); shell commands run without isolation. Docker sandbox mode still works if Docker Desktop is installed.
• API keys are stored via Windows Credential Manager.
• Process management uses taskkill for cleanup.

Windows (WSL2)

Alternatively, use WSL2 for a Linux environment:

# 1. Install WSL2 (PowerShell as admin)
wsl --install -d Ubuntu

# 2. Open Ubuntu terminal, then follow Linux (Ubuntu) steps above

When running octos serve inside WSL2, the dashboard is accessible from your Windows browser at http://localhost:8080 (WSL2 auto-forwards ports).

Docker

docker compose --profile gateway up -d

Deploy Script Reference

./scripts/local-tenant-deploy.sh [OPTIONS]

Options:
  --minimal          CLI + chat only (no channels, no dashboard)
  --full             All channels + dashboard + app-skills
  --channels LIST    Comma-separated: telegram,discord,slack,whatsapp,feishu,email,twilio,wecom
  --no-skills        Skip building app-skills
  --no-service       Skip launchd/systemd service setup
  --uninstall        Remove binaries and service files
  --debug            Build in debug mode (faster compile, larger binary)
  --prefix DIR       Install prefix (default: ~/.cargo/bin)
  --no-tunnel        Skip frpc tunnel setup even in --full mode
  --tenant-name NAME Tenant subdomain (e.g. "alice")
  --frps-token TOKEN shared frps auth token
  --frps-server ADDR frps server address (recommend a DNS-only host such as frps.example.com)
  --ssh-port PORT    SSH tunnel remote port (default: 6001)
  --domain DOMAIN    Tunnel domain (default: octos-cloud.org)
  --auth-token TOKEN Dashboard auth token (default: auto-generated)

For Windows native installs, use .\scripts\install.ps1 (PowerShell).

What the script does:

1. Checks prerequisites (Rust, platform deps)
2. Builds the octos binary with selected features
3. Builds app-skill binaries (unless --no-skills)
4. Signs binaries on macOS (ad-hoc codesign)
5. Creates the runtime data directory and writes ~/.octos/config.json with mode = "local" or mode = "tenant"
6. Creates a background service when dashboard/API features are enabled
7. Optionally configures the frpc tunnel for tenant deployments

For hosted deployments behind Cloudflare, keep the public site on the apex/wildcard domain and use a separate DNS-only hostname such as frps.example.com for the raw frps control port.

Uninstall / purge:

./scripts/local-tenant-deploy.sh --uninstall
./scripts/local-tenant-deploy.sh --purge
./scripts/local-tenant-deploy.sh --uninstall --purge

• --uninstall removes binaries, octos serve, and frpc service files.
• --purge removes the local data directory only.
• --uninstall --purge does both.

Post-Install Verification

Set API Keys

Set at least one LLM provider key:

# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export ANTHROPIC_API_KEY=sk-ant-...
# Or
export OPENAI_API_KEY=sk-...
# Or use OAuth login
octos auth login --provider openai

Verify

octos --version              # Check binary
octos status                 # Check config + API keys
octos chat --message "Hello" # Quick test

Upgrading

cd octos
git pull origin main
./scripts/local-tenant-deploy.sh --full   # Rebuilds and reinstalls

# If running as a service, restart it:
# macOS:
sudo launchctl unload /Library/LaunchDaemons/io.octos.serve.plist
sudo launchctl load /Library/LaunchDaemons/io.octos.serve.plist
# Linux:
sudo systemctl restart octos-serve

Troubleshooting