Self-Hosting - OpenLegion Docs

Run OpenLegion on your own machine with full control over your infrastructure.

Prefer not to manage infrastructure? Get started with managed hosting — a dedicated server provisioned for you in minutes.

Requirements

Python 3.10+ (CI tested on 3.11 and 3.12)
Docker running. Docker Desktop on macOS / Windows; on Linux either Docker Desktop or docker engine with your user in the docker group (sudo usermod -aG docker $USER, then re-login)
One LLM API key (Anthropic / OpenAI / Moonshot / any of 100+ providers via LiteLLM), or run Ollama locally for a keyless setup
OS: macOS, Linux, or Windows (PowerShell + Docker Desktop with WSL 2)

Install and launch

Clone and install

git clone https://github.com/openlegion-ai/openlegion.git && cd openlegion
./install.sh                     # checks deps, creates .venv, makes CLI global

git clone https://github.com/openlegion-ai/openlegion.git
cd openlegion
powershell -ExecutionPolicy Bypass -File install.ps1

First install downloads ~70 packages and takes 2-3 minutes. The first openlegion start then builds two Docker images (~1 min for the agent image, ~3 min for the browser service).

Start your fleet

openlegion start                 # inline setup on first run, then launch agents

On first run (no credentials configured), openlegion start detects this and offers three paths:

Quick setup here — pick a provider, paste your API key (validated), choose a model, then optionally create your first agent or apply a team template
Open the dashboard — configure everything via the web UI at http://localhost:8420/
Skip — start the runtime and use /addkey later in the REPL

After setup, it launches the mesh host on port 8420, spins up agent containers, and drops you into the interactive REPL. Start chatting with your agents immediately.Team Templates (offered during first-run setup):

Template	Agents	Use Case
`starter`	assistant	Single general-purpose agent
`content`	researcher, writer	Blog / social / email from briefs
`deep-research`	scout, analyst	Multi-source synthesis with citations
`devteam`	pm, engineer, reviewer	Software development team
`monitor`	watcher, analyst	Always-on monitoring
`sales`	researcher, qualifier, outreach	Sales pipeline
`competitive-intel`	tracker, analyst	Competitor pricing/product tracking
`lead-enrichment`	enricher, verifier	Lead list research
`price-intelligence`	crawler, analyst	Price monitoring with anti-bot browser
`review-ops`	collector, responder	G2 / Trustpilot / Capterra / App Store / Google reviews + reply drafts
`social-listening`	listener, reporter	Reddit / HN / X competitor pain-point monitor
`research`	researcher	General-purpose researcher
`opportunity-finder`	scout, evaluator, modeler	Gap-scout + evaluation + modeling

Once the engine is running, open http://localhost:8420/ for the web dashboard (four top-nav tabs: Chat / Work / Team / Settings).

Common operations

# Check status / health of agents
openlegion status                # --wide for cost, --watch N to auto-refresh, --json for machine output

# Run in background (daemon mode)
openlegion start -d              # Log: .openlegion.log | PID: .openlegion.pid
openlegion chat researcher       # Connect to a running agent from another terminal
openlegion stop                  # Clean shutdown of mesh + all openlegion_* containers

# microVM mode (Docker Desktop 4.58+; falls back to standard Docker on failure)
openlegion start --sandbox

# Projects, tasks, pending actions
openlegion projects              # List active projects
openlegion project <ID>          # Single project details
openlegion tasks                 # List durable task records (V2 orchestration)
openlegion pending               # List open operator actions awaiting confirmation
openlegion confirm <NONCE>       # Confirm a pending action
openlegion cancel <NONCE>        # Cancel a pending action

# Wallet (EVM + Solana)
openlegion wallet init           # Generate a 24-word BIP-39 seed (shown ONCE; stored in .env)
openlegion wallet show           # Show wallet addresses on all chains

# Reset (stops + wipes config/, data/, agent skills, Docker volumes; keeps .env)
openlegion reset

Inside the REPL, /add hot-adds a new agent to the running fleet, /edit modifies one, and /remove removes one. See the CLI Reference for the full REPL command surface.

Connect a channel

Channels auto-start when their token resolves — there is no separate enable flag. Add the credential to .env (or use /addkey inside the REPL):

# Telegram — bot token from @BotFather
OPENLEGION_CRED_TELEGRAM_BOT_TOKEN=123456:ABC...

# Discord — bot token; requires Message Content Intent + bot/applications.commands scopes
OPENLEGION_CRED_DISCORD_BOT_TOKEN=MTIz...

# Slack — Socket Mode, both tokens required (no public URL needed)
OPENLEGION_CRED_SLACK_BOT_TOKEN=xoxb-...
OPENLEGION_CRED_SLACK_APP_TOKEN=xapp-...

# WhatsApp — Cloud API (Graph v21.0); text-only, non-text dropped
OPENLEGION_CRED_WHATSAPP_ACCESS_TOKEN=EAAx...
OPENLEGION_CRED_WHATSAPP_PHONE_NUMBER_ID=1234...

On the next openlegion start, the channel prints a pairing code; send /start <code> from your account to the bot to link it as the owner.

WhatsApp in production must set WHATSAPP_APP_SECRET for HMAC webhook signature verification. Without it (when MESH_AUTH_TOKEN is also set), the channel startup raises a RuntimeError. Also strongly recommended: set OPENLEGION_SYSTEM_WHATSAPP_VERIFY_TOKEN so the verify token stays stable across restarts.

Webhooks are created from the engine dashboard (System tab → Integrations); there is no openlegion webhooks command. Each hook is reachable at POST /webhook/hook/<hook_id> with an optional HMAC-SHA256 signature; bodies are capped at 1 MB and truncated to 3000 chars when dispatched to agents.

Next steps

Architecture

Understand how agents, the mesh host, and trust zones work together.

CLI Reference

All CLI commands and interactive REPL commands.

Configuration

Customize agents, permissions, models, and budgets.

Coordination

How agents collaborate: blackboard, pub/sub, handoffs, lanes.

​Requirements

​Install and launch

​Common operations

​Connect a channel

​Next steps

Architecture

CLI Reference

Configuration

Coordination

Requirements

Install and launch

Common operations

Connect a channel

Next steps