Architecture

How MUXI components work together

Ask ChatGPT Ask Claude.ai Open in Cursor

MUXI is a layered system: CLI and SDKs talk to Servers, which manage Formations running on Runtimes. The Registry distributes formations.

System Overview

---
config:
  layout: elk
  elk:
    nodePlacementStrategy: LINEAR_SEGMENTS
---
flowchart TB
    subgraph Clients
        CLI[CLI]
        SDKs[SDKs]
        MCP_Clients["MCP Clients
(Claude, Cursor)"]
    end

    subgraph Infrastructure
        Server["Server (:7890)"]
        RCE["Skills RCE (:7891)"]
        subgraph Formations["Formation Runtimes
(:8001-8999)"]
            F1[Formation A]
            F2[Formation B]
            F3[Formation C]
        end
    end

    Registry[Registry]

    CLI --> Server
    SDKs --> Server
    MCP_Clients --> Server
    CLI -.-> Registry
    Server --> Formations
    Formations --> RCE

---
config:
  layout: elk
  elk:
    nodePlacementStrategy: LINEAR_SEGMENTS
---
flowchart TB
    subgraph Clients
        CLI[CLI]
        SDKs[SDKs]
        MCP_Clients["MCP Clients<br>(Claude, Cursor)"]
    end

    subgraph Infrastructure
        Server["Server (:7890)"]
        RCE["Skills RCE (:7891)"]
        subgraph Formations["Formation Runtimes<br>(:8001-8999)"]
            F1[Formation A]
            F2[Formation B]
            F3[Formation C]
        end
    end

    Registry[Registry]

    CLI --> Server
    SDKs --> Server
    MCP_Clients --> Server
    CLI -.-> Registry
    Server --> Formations
    Formations --> RCE

Components

Server: Orchestration platform

Manages formation lifecycle, routes requests, handles auth, monitors health. Written in Go.

Default port: 7890

Runtime: Execution environment

Runs agent logic, manages memory, calls LLMs, executes tools. Exposes a REST API and an MCP server at /mcp for AI-native clients. Written in Python (FastAPI*).

Default ports: 8001-8999

CLI: Command-line tool

Creates formations, deploys to servers, manages secrets. Written in Go.

SDKs: Client libraries

Python, TypeScript, Go, etc. Build apps, chat with formations, manage sessions, fire triggers.

Registry: Distribution hub

Share and discover formations. Version management. Like npm for agents.

The runtime ships as a native SIF image for Linux. On macOS/Windows, run via Docker; on Linux, run SIF directly (or Docker if preferred).

Request Flow

sequenceDiagram
    participant C as Client
    participant S as Server
    participant F as Formation
    participant L as LLM

    C->>S: POST /api/my-formation/v1/chat
    S->>S: Authenticate (HMAC or API key)
    S->>F: Proxy request
    F->>F: Load context (memory, knowledge)
    F->>F: Select agent
    F->>L: Send prompt
    L-->>F: Response
    F->>F: Update memory
    F-->>S: Response
    S-->>C: Response

sequenceDiagram
    participant C as Client
    participant S as Server
    participant F as Formation
    participant L as LLM

    C->>S: POST /api/my-formation/v1/chat
    S->>S: Authenticate (HMAC or API key)
    S->>F: Proxy request
    F->>F: Load context (memory, knowledge)
    F->>F: Select agent
    F->>L: Send prompt
    L-->>F: Response
    F->>F: Update memory
    F-->>S: Response
    S-->>C: Response

MCP clients can also connect directly to a formation's /mcp endpoint, bypassing the server. The MCP interface exposes the same client API as tools, with the same authentication. See Connect via MCP.

Formation Structure

Everything your AI needs in one directory:

my-formation/
├── formation.afs      # Main configuration
├── agents/            # Agent definitions (listed in formation manifest)
│   ├── researcher.afs
│   └── writer.afs
├── mcp/               # MCP tool servers (listed in formation manifest)
│   └── web-search.afs
├── a2a/               # Agent-to-agent services (listed in formation manifest)
│   └── external-api.afs
├── skills/            # Agent skills with SKILL.md files
│   └── data-analysis/
│       └── SKILL.md
├── knowledge/         # RAG sources (any location in formation)
│   └── docs/
├── secrets.enc        # Encrypted credentials
└── secrets.example    # Template for required secrets

Formation placement (concepts → files/dirs)

Concept	Where it lives
LLM Config	`formation.afs` (`llm:` section) with per-agent overrides in `agents/*.afs`
Agents	`agents/*.afs` - listed in formation manifest, define role, specialties
Overlord	`formation.afs` (`overlord:` workflow, clarification settings) + `SOUL.md`
Workflows	`formation.afs` (`overlord.workflow:` auto-decomposition, timeouts)
Memory	`formation.afs` (`memory:` buffer, working, persistent config)
Tools & MCP	`mcp/*.afs` - listed in `mcp.servers`; `formation.afs` (`mcp:` global settings)
Agent-to-Agent	`a2a/*.afs` - listed in `a2a.outbound.services`; `formation.afs` (`a2a:` config)
Skills	`skills/*/SKILL.md` files with scripts, references, assets
Knowledge	`knowledge/` files, referenced in `agents/*.afs` (`knowledge:` section)
Scheduled Tasks	`formation.afs` (`scheduler:` config) - users schedule via natural language
Async Processing	`formation.afs` (`async:` threshold, webhooks)
Secrets	`secrets.enc` - referenced as `${{ secrets.NAME }}` anywhere
User Credentials	`${{ user.credentials.NAME }}` - per-user secrets bound at runtime
Clarification	`formation.afs` (`overlord.clarification:` settings)
Server/API	`formation.afs` (`server:` host, port, API keys)
Logging	`formation.afs` (`logging:` destinations, formats)
Versioning	`formation.afs` (`schema:`, `version:`, `runtime:` fields)

Inside a Formation

---
config:
  layout: elk
  elk:
    nodePlacementStrategy: LINEAR_SEGMENTS
---
flowchart TB
    subgraph Formation["Formation Runtime"]
        Overlord["Overlord (Orchestrator)"]
        Memory["Memory (3-tier)"]

        subgraph Agents
            A1[Agent]
            A2[Agent]
            A3[Agent]
            A4[Agent]
        end

        Tools[MCP Tools]

        Overlord <--> Memory
        Overlord --> Agents
        Agents --> Tools
    end

---
config:
  layout: elk
  elk:
    nodePlacementStrategy: LINEAR_SEGMENTS
---
flowchart TB
    subgraph Formation["Formation Runtime"]
        Overlord["Overlord (Orchestrator)"]
        Memory["Memory (3-tier)"]

        subgraph Agents
            A1[Agent]
            A2[Agent]
            A3[Agent]
            A4[Agent]
        end

        Tools[MCP Tools]

        Overlord <--> Memory
        Overlord --> Agents
        Agents --> Tools
    end

Deployment Models

Local Development

muxi dev → Runtime (localhost:8001)

Single Server

Server (:7890)
  ├── Formation A (:8001)
  ├── Formation B (:8002)
  └── Formation C (:8003)

Multi-Server

Load Balancer
     ├── Server-East (:7890) → Formations
     └── Server-West (:7890) → Formations

Technology Stack

Component	Technology	Why
Server	Go	Single binary, fast, concurrent
Runtime	Python + FastAPI (as native SIF image)	AI ecosystem, async, OneLLM
Skills RCE	Go	Sandboxed code execution for skill scripts
CLI	Go	Cross-platform, single binary
SDKs	Python, TS, Go	Native experience per language

Design Principles

MUXI is infrastructure, not a framework. It deploys anywhere and integrates with anything.

YAML configuration - Simple, versionable, shareable
Encrypted secrets - Not environment variables
MCP for tools - Standard protocol, any server works
Multi-agent - Specialized agents, coordinated work
Portable - Works on any cloud, any platform

Versioning & compatibility

Formation schema follows semver; new minor versions stay backward compatible, breaking changes land in majors.
Pin server/runtime versions together for production; upgrade runtime before server when possible.
Regenerate/validate formations after upgrades to catch schema or tooling changes early.

Next Steps

Request Lifecycle - Detailed request flow
Security Model - Authentication layers
Reference - Building formations

Server: Orchestration platform

Runtime: Execution environment

CLI: Command-line tool

SDKs: Client libraries

Registry: Distribution hub

We use cookies