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.
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 - Formation lifecycle management │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ MUXI Runtime ◄── 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
# Base install (covers almost all use cases)
pip install muxi-runtime
# PyTorch variant — for local embedding models without an ONNX export
pip install 'muxi-runtime[pytorch]'
# CUDA variant — GPU-accelerated ONNX/PyTorch models + FAISS-GPU (NVIDIA only)
# Must uninstall CPU-only packages first to avoid conflicts:
pip uninstall -y faiss-cpu faissx onnxruntime
pip install 'muxi-runtime[cuda]'
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())
Docker Images
MUXI Runtime ships three image variants. All support linux/amd64 and linux/arm64 (except CUDA).
Most users should use the base variant. The PyTorch and CUDA variants exist for specific embedding workloads described below.
| Variant | SIF size | Description | Status |
|---|---|---|---|
default (base) |
~600 MB | Lean runtime — covers the vast majority of use cases | Stable |
pytorch |
larger | Adds CPU-only PyTorch for local embedding models that lack ONNX exports | Stable |
cuda |
largest | GPU-accelerated: ONNX and PyTorch local models + FAISS-GPU for faster vector ops | Experimental |
When to use each variant:
default— the right choice for almost everyone. Uses ONNX-based local embedding models (fast, lightweight) and CPU FAISS.pytorch— only needed when you want to run a local embedding model that does not have an ONNX export and therefore requires the full PyTorch runtime.cuda— recommended for production workloads running on servers with NVIDIA GPUs. Supports both ONNX and PyTorch local models, and ships with FAISS-GPU for significantly faster vector similarity operations.
# Build the default (base) variant
./scripts/build/runtime.sh
# Build the PyTorch variant (requires default built first)
./scripts/build/runtime.sh --variant pytorch
# Build the CUDA variant (experimental, linux/amd64 + NVIDIA tooling required)
./scripts/build/runtime.sh --variant cuda
# Cross-compile for a specific platform
./scripts/build/runtime.sh --platform linux/amd64 --variant pytorch
SIF (Singularity/Apptainer)
Each variant can be converted to a .sif artifact for use with MUXI Server:
./scripts/build/sif.sh # default
./scripts/build/sif.sh --variant pytorch
./scripts/build/sif.sh --variant cuda # experimental
./scripts/build/sif.sh --arch amd64 # force architecture
Note: On macOS and Windows the correct SIF architecture is always
linux-amd64, regardless of host CPU.linux-arm64SIFs only apply on native arm64 Linux hosts (e.g. AWS Graviton).CUDA variant is experimental. It has not been end-to-end validated against live GPUs in CI and only builds on
linux/amd64hosts with NVIDIA tooling.
Development
git clone https://github.com/muxi-ai/runtime
cd runtime
pip install -e ".[dev]"
# Unit and integration tests
pytest tests/unit -v
pytest tests/integration -v
# E2E tests (standalone scripts, not pytest)
cd e2e && python run_all_tests.py # full suite
cd e2e && python run_random_tests.py 10 # random sample
cd e2e/tests/<area> && python test_<name>.py # single test
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.
Metadata
Release files for muxi-runtime 1.20260928.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| muxi_runtime-1.20260928.0.tar.gz | 2.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| muxi_runtime-1.20260928.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 4.5 MB
Release files / muxi_runtime-1.20260928.0.tar.gz
| Download URL | muxi_runtime-1.20260928.0.tar.gz |
|---|---|
| Size | 2.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4cb56b3e4225afbc1496b797abb2f836619e3c38984efad3c48f19a8408d999a
|
|
BLAKE2b-256 checksum How to use checksums |
ae68807d804d3cdf500ec3e7207e88f839d509b0a623a159e0e3947358b2ee12
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / muxi_runtime-1.20260928.0-py3-none-any.whl
| Download URL | muxi_runtime-1.20260928.0-py3-none-any.whl |
|---|---|
| Size | 2.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3d1ad144ad48b5e92c740aa090a99a0c7c3f09ce94be8444b03b0d9a12dd35cc
|
|
BLAKE2b-256 checksum How to use checksums |
29b2d74538a811ae94e2dcff3281ac6cead7e85fa6d73a9001e7f9d39c072c69
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency log
