openlegion

<p align="center">
  <img width="450" alt="openlegion-logo-new" src="https://github.com/user-attachments/assets/08912b04-8df1-4473-b679-6bbac0c3ae2f" />
</p>
<h3 align="center">
  <b>The AI agent framework built for builders who can't afford a security incident.</b>
</h3>
<div align="center">
   
[![License: BSL 1.1](https://img.shields.io/badge/license-BSL%201.1-orange.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![Tests: 2240](https://img.shields.io/badge/tests-2240%20passing-brightgreen)](https://github.com/openlegion-ai/openlegion/actions/workflows/test.yml)
[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/mXNkjpDvvr)
[![Twitter](https://img.shields.io/badge/Twitter-@openlegion-1DA1F2?logo=x&logoColor=white)](https://x.com/openlegion)
[![LiteLLM](https://img.shields.io/badge/LLM-100%2B%20providers-orange.svg)](https://litellm.ai)
[![Docker](https://img.shields.io/badge/isolation-Docker%20%2B%20microVM-blue.svg)]()
   
</div>

> **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](#quick-start) · [Full Setup Guide](QUICKSTART.md) · [Why Not OpenClaw?](#why-not-openclaw) · [Docs](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

- [Quick Start](#quick-start)
- [Why Not OpenClaw?](#why-not-openclaw)
- [What It Does](#what-it-does)
- [Architecture](#architecture)
- [Mesh Host](#mesh-host)
- [Agent Architecture](#agent-architecture)
- [Memory System](#memory-system)
- [Triggering & Automation](#triggering--automation)
- [Cost Tracking & Budgets](#cost-tracking--budgets)
- [Security Model](#security-model)
- [CLI Reference](#cli-reference)
- [Configuration](#configuration)
- [MCP Tool Support](#mcp-tool-support)
- [Testing](#testing)
- [Dependencies](#dependencies)
- [Project Structure](#project-structure)
- [Design Principles](#design-principles)

---

## Quick Start

**Requirements:** Python 3.10+, Docker (running), an LLM API key ([Anthropic](https://console.anthropic.com/) / [Moonshot](https://platform.moonshot.cn/) / [OpenAI](https://platform.openai.com/api-keys))

**macOS / Linux:**

```bash
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):**

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

> First install downloads ~70 packages and takes 2-3 minutes. Subsequent installs are fast.
>
> **Need help?** See the **[full setup guide](QUICKSTART.md)** for platform-specific instructions and troubleshooting.

```bash
# Add more agents from the REPL
/add

# Run in background
openlegion start -d
openlegion chat researcher   # connect from another terminal
openlegion stop              # clean shutdown
```

---

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

1. **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.

2. **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 `/costs` in the REPL.

3. **Acts autonomously** — cron schedules, heartbeat probes, webhook triggers, and file watchers let agents work without being prompted.

4. **Self-aware and self-improving** — agents understand their own permissions, budget, fleet topology, and system architecture via auto-generated `SYSTEM.md` and live runtime context. They learn from tool failures and user corrections, injecting past learnings into future sessions.

5. **Self-extends** — agents write their own Python skills at runtime and hot-reload them. Agents can also spawn sub-agents for specialized work.

6. **Multi-channel** — connect agents to Telegram, Discord, Slack, and WhatsApp. Also accessible via CLI and API.

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

8. **Tracks and caps spend** — per-agent LLM cost tracking with daily and monthly budget enforcement.

9. **Fails over across providers** — configurable model failover chains cascade across LLM providers with per-model health tracking and exponential cooldown.

10. **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.

```
┌──────────────────────────────────────────────────────────────────────────┐
│                           Use

[truncated…]