openlegion-ai / openlegion

The AI agent framework built for builders who can't afford a security incident. [ ]() > **Autonomous AI agent fleets — isolated, auditable, and production-ready.** > Every agent runs in its own Docker container. API keys never leave the vault. > Chat via Telegram, Discord, Slack, or WhatsApp. Built-in cost controls. 100+ LLM providers. Quick Start · Full Setup Guide · Why Not OpenClaw? · Docs --- Demo https://github.com/user-attachments/assets/8bd3fe95-5734-474d-92f0-40616daf91ad > → inline setup → multiple agents running. > Live cost tracking. No configuration files edited by hand. > Connect Telegram, WhatsApp, Slack, and Discord. Table of Contents • Quick Start • Why Not OpenClaw? • What It Does • Architecture • Mesh Host • Agent Architecture • Memory System • Triggering & Automation • Cost Tracking & Budgets • Security Model • CLI Reference • Configuration • MCP Tool Support • Testing • Dependencies • Project Structure • Design Principles --- Quick Start **Requirements:** Python 3.10+, Docker (running), an LLM API key (Anthropic / Moonshot / OpenAI) **macOS / Linux:** **Windows (PowerShell):** > First install downloads ~70 packages and takes 2-3 minutes. Subsequent installs are fast. > > **Need help?** See the **full setup guide** for platform-specific instructions and troubleshooting. --- Why Not OpenClaw? OpenClaw is the most popular personal AI assistant framework — 200K+ GitHub stars, brilliant for single-user use. For production workloads and team deployments, it has documented problems: • **42,000+ exposed instances** with no authentication (Bitsight, Feb 2026) • **341 malicious skills** found stealing user data (Koi Security / 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. | | OpenClaw | OpenLegion | |---|---|---| | **API key storage** | Agent config files | Vault proxy — agents never see keys | | **Agent isolation** | Process-level | Docker container per agent + microVM option | | **Cost controls** | None | Per-agent daily + monthly budget caps | | **Multi-agent routing** | LLM CEO agent | Fleet model — blackboard + pub/sub coordination | | **LLM providers** | Broad | 100+ via LiteLLM with health-tracked failover | | **Test coverage** | Minimal | 2240 tests including full Docker E2E | | **Codebase size** | 430,000+ lines | ~32,000 lines — auditable in a day | --- 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, heartbeat monitoring, and file watchers — without being prompted. **2240 tests passing** across **~32,000 lines** of application code. **Fully auditable in a day.** No LangChain. No Redis. No Kubernetes. No CEO agent. BSL License. • **Security by architecture** — every agent runs in an isolated Docker container (microVM when available). API keys live in the credential vault — agents call through a proxy and never handle credentials directly. Defense-in-depth with 6 security layers. • **Production-grade cost control** — per-agent LLM token tracking with enforced daily and monthly budget caps at the vault layer. Agents physically cannot spend what you haven't authorized. View live spend with in the REPL. • **Acts autonomously** — cron schedules, heartbeat probes, webhook triggers, and file watchers let agents work without being prompted. • **Self-aware and self-improving** — agents understand their own permissions, budget, fleet topology, and system architecture via auto-generated and live runtime context. They learn from tool failures and user corrections, injecting past learnings into future sessions. • **Self-extends** — agents write their own Python skills at runtime and hot-reload them. Agents can also spawn sub-agents for specialized work. • **Multi-channel** — connect agents to Telegram, Discord, Slack, and WhatsApp. Also accessible via CLI and API. • **Real-time dashboard** — web-based fleet observability with consolidated navigation, slide-over chat panels, keyboard command palette, grouped request traces, live event streaming, streaming broadcast with real-time per-agent responses, LLM prompt/response previews, agent management, agent settings editor (personality, instructions, preferences, heartbeat rules, memory, activity logs, learnings), cost charts, cron management, and embedded KasmVNC viewer for persistent browser agents. • **Tracks and caps spend** — per-agent LLM cost tracking with daily and monthly budget enforcement. • **Fails over across providers** — configurable model failover chains cascade across LLM providers with per-model health tracking and exponential cooldown. • **Token-level streaming** — real-time token-by-token LLM responses across CLI, dashboard, Telegram, Discord, and Slack with progressive message editing and graceful non-streaming fallback. --- Architecture OpenLegion's architecture separates concerns across three trust zones: untrusted external input, sandboxed agent containers, and a trusted mesh host that holds credentials and coordinates the fleet. All inter-agent communication flows through the mesh — no agent has direct network access or peer-to-peer connections. Trust Zones | Level | Zone | Description | |-------|------|-------------| | 0 | Untrusted | External input (webhooks, user prompts). Sanitized before reaching agents. | | 1 | Sandboxed | Agent containers. Isolated filesystem, no external network, no credentials. | | 2 | Trusted | Mesh host. Holds creden…