openlegion

Run autonomous, self-hosted AI agent fleets that are isolated, auditable, and production-ready. Every agent runs in its own Docker container, API keys never leave the credential vault, and per-agent budgets cap spend. A source-available, security-first OpenClaw alternative for teams. Chat via Telegram, Discord, Slack, or WhatsApp. 100+ LLM providers via LiteLLM.

What is OpenLegion? · Quick Start · OpenLegion vs OpenClaw · Security Model · Docs

Demo

https://github.com/user-attachments/assets/8bd3fe95-5734-474d-92f0-40616daf91ad

openlegion start → inline setup → multiple agents running. Live cost tracking. No configuration files edited by hand. Connect Telegram, WhatsApp, Slack, and Discord.

Table of Contents

• What is OpenLegion?
• Who is OpenLegion for?
• Quick Start
• OpenLegion vs OpenClaw
• What It Does
• Architecture
• Mesh Host
• Agent Architecture
• Operator & Teams
• Memory System
• Triggering & Automation
• Cost Tracking & Budgets
• Security Model
• CLI Reference
• Configuration
• MCP Tool Support
• Testing
• Dependencies
• Project Structure
• Design Principles
• FAQ

What is OpenLegion?

OpenLegion is a secure, self-hosted AI agent runtime for running fleets of autonomous AI agents in production. Each agent runs in its own hardened Docker container (or microVM), with its own memory, tools, schedule, and budget. Agents never hold API keys - every LLM and API call routes through a central credential vault that also enforces per-agent spend limits. A trusted mesh host coordinates the fleet through shared state and pub/sub events, with permission ACLs checked on every cross-agent action.

It is source-available under the PolyForm Perimeter License 1.0.1: you can self-host it for free — including for your own commercial, internal operations — read the entire ~77,000-line codebase, and audit it in a day. The one thing you can't do is offer it to others as a product or service that competes with OpenLegion (e.g. reselling it as your own hosted/managed service). Managed hosting is available from OpenLegion LLC for teams that prefer not to run their own infrastructure. OpenLegion is built as a production- and team-focused OpenClaw alternative - it keeps the autonomy of single-user assistant frameworks and adds container isolation, credential vaulting, per-agent budgets, and auditable workflows.

In one line: a multi-agent framework where security, isolation, and cost control are part of the architecture, not an afterthought.

Who is OpenLegion for?

• Developers and AI builders who want a programmable, self-hosted runtime for multi-agent systems instead of a hosted black box.
• Self-hosters and technical founders who need AI agents that run on their own infrastructure, with data and credentials never leaving their control.
• Teams running agents in production that need per-agent budgets, permission ACLs, Docker/microVM isolation, and a codebase small enough to audit.
• OpenClaw, CrewAI, LangGraph, and AutoGen users who have outgrown single-user or library-only setups and now need security and cost controls around their agents.
• Managed-hosting customers who want the same runtime without operating the infrastructure themselves.

If you just want a personal assistant on one machine, a single-user tool is simpler. OpenLegion is for when agents become shared, always-on, or handle anything you cannot afford to leak or overspend.

Quick Start

Requirements: Python 3.10+, Docker (running), at least one LLM provider key (Anthropic, OpenAI, Gemini, Moonshot, Deepseek, xAI, Groq, Minimax, Zai, or Ollama — the setup wizard walks you through it; existing Anthropic Claude CLI or OpenAI Codex CLI logins can be imported).

macOS / Linux:

git clone https://github.com/openlegion-ai/openlegion.git && cd openlegion
./install.sh                     # checks deps, creates venv, makes CLI global
openlegion start                 # inline setup on first run, then launch agents

Windows (PowerShell):

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

Windows note: Docker Desktop (not Docker Engine) is required on Windows. WSL2 must be enabled. See Docker's WSL2 backend guide if containers fail to start.

First install downloads dependencies into a venv; this may take several minutes the first time. Subsequent installs are fast.

First run: On the very first openlegion start, Docker builds the openlegion-agent:latest and openlegion-browser:latest images from the Dockerfile.agent and Dockerfile.browser in the repo root. The browser image is significantly larger (Camoufox + KasmVNC + Openbox + Xvnc) and can take several minutes with no progress output — this is normal. Subsequent starts are fast.

Background mode: openlegion start -d polls for startup for up to 90 seconds. If a Docker image build is needed on first run, this timeout may be exceeded — wait for the build to finish and re-run openlegion start -d.

First run also creates: config/agents.yaml, config/permissions.json, config/mesh.yaml, agent volumes, and an operator agent that you didn't define — that's a built-in fleet-management agent (lighter resource caps, excluded from cost/quota math). See CLI Reference for openlegion reset if you want to wipe state and start over.

Need help? See the full setup guide for platform-specific instructions and troubleshooting.

Common commands

# Start (interactive REPL); use /add inside the REPL to register more agents
openlegion start

# Run in background
openlegion start -d
openlegion chat <agent_name>   # connect from another terminal to an agent you created
openlegion stop                # clean shutdown
openlegion reset               # destructive: wipe config/, data/, agent_tools/* (keeps .env)

OpenLegion vs OpenClaw

OpenLegion is an OpenClaw alternative built for production and team use. OpenClaw is the most popular personal AI assistant framework (200K+ GitHub stars) and is genuinely great for single-user setups. The trade-off shows up once agents become shared, always-on, or handle untrusted input - areas where it has documented security and cost gaps:

• 42,000+ exposed instances with no authentication (Bitsight, Feb 2026)
• 341 malicious skills found stealing user data (Koi Security via The Hacker News)
• CVE-2026-25253: one-click remote code execution
• No per-agent cost controls — runaway spend is a real risk
• No deterministic routing — a CEO agent (LLM) decides what runs next
• API keys stored directly in agent config

OpenLegion was designed from day one assuming agents will be compromised.

What It Does

OpenLegion is an autonomous AI agent framework for running multi-agent fleets in isolated Docker containers. Each agent gets its own memory, tools, schedule, and budget — coordinated through blackboard shared state and pub/sub events with no LLM routing layer.

Chat with your agent fleet via Telegram, Discord, Slack, WhatsApp, or CLI. Agents act autonomously via cron schedules, webhooks, and heartbeat monitoring — without being prompted.

5800+ tests passing across 193 test files. Fully auditable in a day. No LangChain. No Redis. No Kubernetes. No CEO agent. Source-available (PolyForm Perimeter).

1. **Security by archi