# MUXI - The AI Application Server

> No one builds their own Nginx to deploy a website. No one should reinvent infrastructure to build AI.

MUXI is an open-source AI application server for running AI agents in production. Not a framework. Not a wrapper. A complete server stack. MUXI V1 provides stable contracts across the Server, Runtime, CLI, and 12 SDKs.

## What is MUXI?

MUXI (Multiplexed eXtensible Intelligence, pronounced /ˈmʌk.siː/) is production infrastructure purpose-built for AI agents. Unlike frameworks that you import as libraries, MUXI is a complete server stack that runs, orchestrates, and manages multi-agent systems at scale.

**The mental model:**

How it runs, like a web application:
| Layer | Web World | MUXI |
|-------|-----------|------|
| Server | Nginx | MUXI Server (Go) |
| Runtime | Node / Python | MUXI Runtime (Python) |
| Application | Your code | Formation (.afs) |

How you ship it, like Docker:
| Concept | Docker | MUXI |
|---------|--------|------|
| Engine | Docker Engine | Server + Runtime |
| Definition | Dockerfile | Formation |
| Registry | Docker Hub | MUXI Registry |
| CLI | `docker` | `muxi` |

**The key insight:** You build applications ON TOP of MUXI using SDKs. Your frontend, mobile app, or backend talks to MUXI via API. MUXI handles orchestration, memory, multi-tenancy, and observability. That's what makes it infrastructure, not a framework.

**Core Philosophy:** Agents are native primitives – declared in portable `.afs` files, orchestrated at the infrastructure layer, scaled like containers. No frameworks to import. No infrastructure to build. Just declare and deploy.

## Who Is MUXI For?

**Platform Builders**: Building a SaaS with AI features? MUXI handles orchestration, memory, and multi-tenancy so you can focus on your product.

**Internal Tool Builders**: Deploying AI assistants for your team? MUXI gives you group-based RBAC, observability, and production infrastructure out of the box.

**Developers Tired of Framework Hell**: Spent months on LangChain orchestration code? MUXI replaces it with YAML configuration and a single deploy command.

You could build the next OpenClaw on MUXI. That's the point.

## Key Differentiators

- **Infrastructure, not a framework**: Deploy with `muxi deploy` – agents go live instantly
- **API-first architecture**: HTTP/REST and SSE, plus MCP and A2A integrations and 12 official SDKs
- **Formation-based deployment**: Complete AI systems defined in the Agent Formation Standard
- **LLM-agnostic**: Use any provider (OpenAI, Anthropic, Google, AWS, Azure, local models)
- **Multi-tenant by design**: Built-in user isolation, per-user credentials, and role-based access control (RBAC) through groups
- **Self-hosted**: Complete data sovereignty, runs anywhere (on-prem, cloud, air-gapped)
- **Open source**: Elastic License 2.0 (ELv2) for the Server and Runtime; Apache 2.0 for the CLI, SDKs, schemas, and formations

## Core Concepts

### Formations

A formation is a complete AI system packaged as a single deployable unit. MUXI is the reference implementation of the [Agent Formation Standard](https://agentformation.org), an open specification for declarative AI systems.

Like a Dockerfile for containers, but for AI agents. Formations include:

- Agent definitions and configurations
- Domain knowledge (files, URLs, documents)
- MCP (Model Context Protocol) tool connections
- Standard Operating Procedures (SOPs)
- Skills and sandboxed code execution
- Triggers, schedules, webhooks, and outbound transformers
- Memory, access control, proactive behavior, and self-tuning
- Settings and secret references

Formations are version-controlled directory packages anchored by `.afs` YAML files (`.yaml` also works), with optional knowledge, skills, triggers, transformers, and policy files. The complete package is portable and deployable with one command.

### The MUXI Stack

Four architectural layers:

1. **Clients** - CLI, MCP, and 12 SDKs: Python, TypeScript, Go, Ruby, PHP, C#, Java, Kotlin, Swift, Dart, Rust, and C++
2. **APIs** - REST endpoints for deployment, chat, streaming, memory, knowledge, and operations
3. **Runtime** - Core orchestration: agents, memory, tools, task execution
4. **Server** - Self-hosted infrastructure for production deployments

Developers build ON TOP of MUXI. Your app calls MUXI's API. MUXI handles everything else.

### Agent-Native Infrastructure

Agents aren't bolted on – they're native primitives. State persistence, task orchestration, and resource management happen at the infrastructure layer. Agents are declared, deployed, and scaled like containers.

## Key Features

### Deployment & Operations

- **One-command deployment**: `muxi deploy` and you're live
- **GitOps workflow**: Version-controlled formations, CI/CD integration, updates, and rollbacks
- **Managed runtimes**: The Go server launches isolated formation runtimes using Apptainer/SIF on Linux and a Docker-based runtime runner on macOS and Windows
- **Safe state preservation**: Updates and rollbacks retain persistent memory and self-tuning state
- **Draft workflow**: Develop and test draft formations before deploying them live

### Intelligence & Execution

- **Overlord orchestration engine**: ~10,000-line core that powers multi-agent coordination, task routing, and workflow execution
- **Intelligent task decomposition**: Complex requests automatically broken into executable subtasks
- **Adaptive workflow execution**: SOP-driven workflows, hierarchical model selection, and optional workflow replanning
- **Agent collaboration**: Coordination within formations and across services through A2A
- **Multimodal support**: Images, PDFs, audio, video processing out-of-the-box

### Memory & Context

- **Layered memory**: Buffer memory for recent conversation, working/vector memory for semantic context, persistent storage for long-term facts, and derived user synopses
- **Scoped memory**: User, group, and formation scopes with grant-controlled shared writes
- **Memory lifecycle**: Ingestion and distillation APIs, provenance, rebuild, backfill, forgetting, decay, compaction, and pruning
- **Memory intelligence**: Knowledge graph, Captain's Log, and lesson recording support
- **Domain knowledge**: Files and remote sources with vector, tree, tree-vector, or hybrid reasoning RAG, scheduled synchronization, and incremental re-embedding

### Integration & Tools

- **MCP Protocol native**: Access 1,000+ tools (GitHub, Slack, Postgres, Stripe, etc.)
- **Multi-user MCP access**: Per-user OAuth tokens and API keys with encryption
- **Agent Skills**: Progressive-disclosure SKILL.md packages with scripts executed in an isolated remote code execution (RCE) sandbox
- **Built-in tools**: File generation, artifact recall, history recall, lesson recording, background-job monitoring, and coding-agent delegation
- **LLM provider agnostic**: Dozens of built-in providers, local models, and OpenAI-compatible endpoints through OneLLM
- **Model flexibility**: Per-formation, agent, SOP, trigger, skill, and workflow-step model selection with aliases and fallback support

### MCP Without the Bloat

Large MCP catalogs can consume significant context if every tool schema is sent with every request. MUXI takes a different approach:

- **Load once**: Tool definitions are fetched and indexed at startup
- **Select on demand**: Agents receive the tools relevant to the current request
- **Control the surface**: Formation, group, server, and agent-level allow/deny rules can filter available tools

This keeps large tool catalogs manageable without injecting every schema into every prompt.

### Production Features

- **Multi-tenancy**: Complete session isolation with per-user credentials
- **Group-based RBAC**: Inheritance, agent and MCP filtering, tool allow/deny rules, and fail-closed membership resolution
- **Real-time streaming**: SSE for chat tokens, progress, tool activity, typed UI widgets, and lifecycle events
- **Built-in observability**: Hundreds of typed events with redaction and pluggable exporters
- **Enterprise resilience**: Circuit breakers, exponential backoff, graceful degradation
- **Idempotent mutations**: Retry-safe chat, trigger execution, and scheduled-job creation through `X-Muxi-Idempotency-Key`
- **Response UI widgets**: Typed options, action links, and MCP resources that clients can render with text fallbacks

### Triggers & Automation

- **Natural language scheduling**: "Check email every hour" or "remind me tomorrow at 2pm"
- **Webhook triggers**: External systems activate agents via HTTP endpoints
- **Outbound transformers**: Route trigger results to external platforms with templates, authentication, retries, and fallbacks
- **Proactive formations**: Notifications, per-user channels, heartbeats, active hours, soul documents, and built-in slash commands
- **Dynamic async execution**: Smart sync/async switching, background jobs, and status tracking

### Developer Experience

- **Standard Operating Procedures**: Define organizational knowledge agents reason over (not rigid workflows)
- **Persistent artifacts**: Generate and recall versioned, encrypted, user-scoped documents, spreadsheets, presentations, charts, and code files
- **Self-tuning**: Review and apply runtime-generated improvement suggestions through the CLI or API
- **Coding-agent delegation**: Run supported headless coding CLIs as isolated asynchronous jobs
- **Type-safe SDKs**: 12 official clients with streaming, retries, authentication, typed errors, and response envelopes

## Quick Start

```bash
# Install (macOS)
brew install muxi-ai/tap/muxi

# Install (Linux)
curl -fsSL https://muxi.org/install | sudo bash

# Install (Windows)
powershell -c "irm https://muxi.org/install | iex"

# Deploy your first formation
muxi pull @muxi/bookkeeping
muxi secrets set OPENAI_API_KEY ••••••••••
muxi deploy --profile production
```

Then build on top:

```python
from muxi import FormationClient

formation = FormationClient(
    server_url="http://localhost:7890",
    formation_id="bookkeeping",
    client_key="<your-client-key>",
)
response = formation.chat(
    {"message": "What's my current balance?"},
    user_id="user_123",
)
```

Your app talks to MUXI. MUXI handles everything else.

## Documentation

Our documentation is available in markdown format for easier parsing:

- Add `.md` to any doc URL: `https://muxi.org/docs/[page].md`
- Full markdown sitemap: https://muxi.org/llms-sitemap.txt
- Most HTML pages include `<link rel="alternate" type="text/markdown">` tags for easier parsing by AI assistants.

## Architecture

MUXI implements the open Agent Formation Standard, where complete AI systems are packaged as `.afs` files.

**Go + Python split**: The Server is written in Go and provides the deployment control plane, process lifecycle, authentication, and routing. The Python Runtime loads each formation and performs agent orchestration, model calls, memory, tool execution, streaming, and observability.

The server manages:

- Formation lifecycle (deploy, update, rollback)
- Draft and live formation processes
- Authentication and HTTP proxy routing
- Runtime versions, health checks, ports, and logs

Each formation runtime manages:

- Agent orchestration, workflows, triggers, and task execution
- Layered and scoped memory
- Knowledge retrieval and synchronization
- MCP tools, Skills, A2A services, and coding delegation
- Chat streaming, artifacts, notifications, and observability

**Registry**: The MUXI Registry is Docker Hub for agents – push, pull, and share formations with version management and access control.

## Use Cases

- **SaaS AI features**: Embed AI capabilities in your application via SDKs
- **Customer support systems**: Multi-agent teams handling tickets, refunds, inquiries
- **Internal tooling**: Automating workflows across GitHub, Slack, Jira, etc.
- **Document processing**: Extract, analyze, and generate reports from files
- **Data analysis platforms**: Query databases, generate visualizations, create reports
- **Booking and scheduling**: Coordinate calendars, send notifications, manage reservations

## Licensing

- **MUXI Server & Runtime**: Elastic License 2.0 (ELv2)
- **Formations, CLI, SDKs**: Apache 2.0
- **Agent Formation Standard**: Apache 2.0 (independent open standard)

**You CAN:**
- Use for internal projects and products
- Build and sell products that use MUXI
- Deploy for clients and customers
- Self-host on your infrastructure

**You CANNOT:**
- Offer MUXI itself as a hosted service (SaaS)

## Technical Details

- **Current generation**: MUXI V1, with coordinated Server, Runtime, CLI, and SDK contracts
- **Client libraries**: 12 official SDKs
- **Observability**: Hundreds of typed lifecycle events with PII and secret redaction
- **Model access**: Cloud providers, local models, and OpenAI-compatible endpoints through OneLLM
- **Deployment**: Go server binary or container, with managed isolated formation runtimes
- **Supported platforms**: Linux, macOS, Windows
- **Protocol support**: HTTP/REST, Server-Sent Events, MCP, and A2A

## Comparison with Alternatives

### vs. Frameworks (LangChain, CrewAI, AutoGen)

MUXI provides the production infrastructure that application frameworks typically leave to each team to build.

| | MUXI | Frameworks |
|---|---|---|
| **Type** | Server infrastructure | Python library |
| **Deployment** | `muxi deploy` | Write deployment code |
| **Configuration** | Declarative `.afs` files | Imperative code |
| **Multi-tenancy** | Built-in isolation | Build yourself |
| **Memory** | Layered, scoped, and lifecycle-managed | Build yourself |
| **Observability** | Typed events and exporters included | Add external tools |
| **RBAC** | Groups, inheritance, and tool filtering | Build yourself |

Think: Flask is a framework. Nginx is infrastructure. You don't import Nginx, you deploy to it.

### vs. AI Assistants (OpenClaw, ChatGPT, Claude)

Different layer entirely. OpenClaw is a personal AI assistant (single-user product). MUXI is infrastructure to build products like OpenClaw, with multi-tenancy, proper memory, and SDKs for integration.

You could build OpenClaw on MUXI. That's the point.

### vs. Cloud AI (Bedrock, Vertex, Azure AI)

Cloud AI = model hosting + APIs + some orchestration primitives.
MUXI = agent-specific runtime with memory, orchestration, multi-tenancy.

We're complementary, not competitive. MUXI connects to major cloud providers, local models, and OpenAI-compatible endpoints through OneLLM.

## Business Model

Open-source with sustainable revenue from support services, not paywalls:

- Core stack is free and self-hostable forever
- GitHub Sponsors for priority support
- Professional services for enterprise deployments
- Public schemas, CLI, SDKs, and formation tooling use the permissive Apache 2.0 license

**Track record**: Built by a developer whose other open-source libraries receive 20M+ monthly downloads – MUXI is production-grade from day one.

## Community & Support

- **Documentation**: https://muxi.org/docs
- **GitHub**: https://github.com/muxi-ai
- **Discussions**: https://muxi.org/community
- **Registry**: https://registry.muxi.org
- **Roadmap**: https://github.com/orgs/muxi-ai/projects/1
- **Sponsors**: https://github.com/sponsors/muxi-ai
- **Email**: hi@muxi.org
- **Twitter**: @muxi_ai

## Who Built This?

Created by Ran Aroussi (x.com/@aroussi), a 35+ year tech veteran whose open-source libraries, excluding MUXI, receive 20M+ monthly downloads. Author of "Production-Grade Agentic AI" (650+ page technical book). No VC funding, no exit timeline – built for long-term sustainability.

## Quick Links

- [Quickstart Guide](https://muxi.org/docs/quickstart)
- [Installation](https://muxi.org/docs/installation)
- [Formation Spec](https://agentformation.org)
- [API Reference](https://muxi.org/docs/reference/api-reference)
- [Examples](https://muxi.org/docs/examples)
- [Contributing Guide](https://muxi.org/contributing)
- [Changelog](https://muxi.org/changelog)

## Common Questions

**Do I need the Server or just the Runtime?**
Most developers want the Server for production deployments. The Runtime is available as a Python library for custom integrations or single-tenant apps.

**What LLM providers are supported?**
Major providers include OpenAI, Anthropic, Google, Azure, AWS Bedrock, Mistral, Cohere, and others. MUXI also supports local models through Ollama and llama.cpp, plus OpenAI-compatible endpoints.

**What is the Agent Formation Standard?**
An open specification for declarative AI systems. MUXI is the reference implementation. Formations are defined in `.afs` files (or `.yaml`) and are portable across AFS-compliant runtimes. Learn more at [agentformation.org](https://agentformation.org).

**How is this different from LangChain?**
LangChain is a framework you import. MUXI is infrastructure you deploy to. LangChain helps you write agent code. MUXI runs agents in production with memory, multi-tenancy, observability, and group-based RBAC built in. You can use LangChain inside MUXI formations if you want, but most won't need it.

**Can I contribute?**
Yes! MUXI is community-driven. Contribute code, docs, formations, bug reports, or feature requests. See the [contributing guide](https://github.com/muxi-ai/muxi/blob/main/CONTRIBUTING.md).

**What about enterprise support?**
Professional services available. Email hi@muxi.org for deployment assistance, custom integrations, and SLA-backed support.

---

**License**: ELv2 (Server/Runtime), Apache 2.0 (everything else)