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

<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 secure AI agent runtime 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: 5800+](https://img.shields.io/badge/tests-5800%2B%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%20Sandbox-blue.svg)]()
   
</div>

> **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?](#what-is-openlegion) · [Quick Start](#quick-start) · [OpenLegion vs OpenClaw](#openlegion-vs-openclaw) · [Security Model](#security-model) · [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

- [What is OpenLegion?](#what-is-openlegion)
- [Who is OpenLegion for?](#who-is-openlegion-for)
- [Quick Start](#quick-start)
- [OpenLegion vs OpenClaw](#openlegion-vs-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)
- [FAQ](#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 Business Source License 1.1 (BSL): you can self-host it for free, read the entire ~77,000-line codebase, and audit it in a day. Managed hosting is available 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;

... (truncated)