MUXI Runtime

The execution engine for AI agent formations.

For most users: Install MUXI CLI for the complete experience. This repo is for contributors and developers embedding the runtime directly.

Important

MUXI Ecosystem

This repository is part of the larger MUXI ecosystem.

📋 Complete architectural overview: See muxi/ARCHITECTURE.md - explains how core repositories fit together, dependencies, status, and roadmap.

What is MUXI Runtime?

MUXI Runtime transforms declarative YAML configurations into running AI systems. It's the core engine that powers the MUXI Server.

Core responsibilities:

• Formation execution - Loads and runs agent configurations from YAML
• Overlord orchestration - Routes requests, manages clarifications, coordinates workflows
• Memory systems - Three-tier memory (buffer, persistent, vector)
• Tool integration - MCP protocol support for external tools
• Multi-tenant isolation - User and session management

Architecture

┌─────────────────────────────────────────────────────┐
│  MUXI Server (Go) - Formation lifecycle management  │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│  MUXI Runtime (Python) ◄── THIS REPO                │
│  ┌───────────────────────────────────────────────┐  │
│  │  Formation Engine (YAML loader & validator)   │  │
│  ├───────────────────────────────────────────────┤  │
│  │  Overlord │ Agents │ Workflow │ Background    │  │
│  ├───────────────────────────────────────────────┤  │
│  │  Memory │ MCP │ A2A │ LLM │ Observability     │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│  External Services (LLM APIs, MCP Servers, DBs)     │
└─────────────────────────────────────────────────────┘

Package Structure

The runtime uses src/muxi/runtime/ to share the muxi namespace with the Python SDK:

src/muxi/runtime/
├── formation/          # Formation engine
│   ├── overlord/       # Central orchestration
│   ├── agents/         # Agent implementations
│   ├── workflow/       # Task decomposition, SOPs
│   ├── server/         # Formation API (FastAPI)
│   └── background/     # Webhooks, scheduling, async
├── services/           # Runtime services
│   ├── memory/         # Memory systems
│   ├── mcp/            # MCP client
│   ├── a2a/            # Agent-to-agent
│   └── llm/            # LLM abstraction
└── datatypes/          # Type definitions

Quick Start

Using with MUXI Server (recommended)

# Install MUXI CLI
curl -fsSL https://muxi.ai/install | sh

# Create and run a formation
muxi new my-assistant
cd my-assistant
muxi dev

Embedding directly

pip install muxi-runtime

from muxi.runtime import Formation
import asyncio

async def main():
    formation = Formation()
    await formation.load("formation.afs")
    overlord = await formation.start_overlord()

    response = await overlord.chat(
        "Hello!",
        user_id="user123"
    )
    print(response)

asyncio.run(main())

Development

git clone https://github.com/muxi-ai/runtime
cd runtime
pip install -e ".[dev]"

# Run tests
pytest tests/unit -v
pytest tests/integration -v
pytest e2e/tests -v

See contributing/README.md for contributor documentation.

Related Repositories

Repo	Description
muxi-ai/muxi	Main repo with architecture docs
muxi-ai/server	Go server that hosts this runtime
muxi-ai/cli	Command-line tool
muxi-ai/sdks	Python, TypeScript, Go SDKs
muxi-ai/schemas	API schemas

Documentation

• User docs: docs.muxi.ai
• Contributor docs: contributing/README.md
• Formation spec: agentformation.org

License

Elastic License 2.0 - Free to use, modify, and embed in products. Cannot be offered as a hosted service.