Quickstart

Go from zero to a running AI agent in 5 minutes

This quickstart gets you from zero to a working AI agent in 5 minutes. You'll install MUXI, create a formation, and test it.

Prerequisites:

  • Terminal access (macOS, Linux, or Windows)
  • OpenAI API key (get one here)
  • 5 minutes

Get started in 5 minutes

  1. Install MUXI

    brew install muxi-ai/tap/muxi

    Expected output:

    ==> Downloading https://github.com/muxi-ai/muxi/releases/...
==> Installing muxi
🍺  /opt/homebrew/bin/muxi
    curl -fsSL https://muxi.org/install | sudo bash

    Expected output:

    [INFO] Downloading MUXI...
[INFO] Installing to /usr/local/bin
[INFO] MUXI installed successfully
    powershell -c "irm https://muxi.org/install | iex"

    Expected output:

    Downloading MUXI...
Installing to C:\Program Files\muxi
MUXI installed successfully

    Verify installation:

    muxi --version

    Expected: muxi version 1.0.0 (or higher)

    Troubleshooting:

    • Command not found? Restart your terminal
    • macOS: brew update && brew install muxi-ai/tap/muxi
    • Linux: Check PATH includes /usr/local/bin

  2. Start the Server

    First time only - generate credentials:

    muxi-server init

    Expected output:

    Generated credentials:
  Key ID:     muxi_key_abc123...
  Secret:     muxi_secret_xyz789...

⚠️  Save these credentials securely!

Config saved to: ~/.muxi/server/config.yaml

    Save these credentials! You'll need them to deploy formations remotely.

    Now start the server:

    muxi-server start

    Expected output:

    [INFO] muxi remote starting...
[INFO] Listening on :7890
[INFO] Server ready

    Leave this terminal open - the server must stay running.

    Troubleshooting:

    • Port already in use? muxi-server --port 7891
    • Check logs: muxi-server logs

  3. Create a Formation

    Open a new terminal:

    muxi new formation my-assistant
cd my-assistant

    This creates:

    my-assistant/
├── formation.afs      # Main configuration
├── agents/            # Agent definitions
├── secrets            # Required secrets template
└── .gitignore

  4. Configure Secrets

    muxi secrets setup

    Enter your OpenAI API key when prompted:

    Setting up secrets for my-assistant...

Required secrets:
  OPENAI_API_KEY (from llm.api_keys)

Enter OPENAI_API_KEY: sk-...

✓ Secrets encrypted and saved

  5. Run Locally

    With the server running (from Step 2), start your formation:

    muxi up

    Expected output:

    ✓ Started my-assistant
✓ Formation running on port 8001

  Draft URL: http://localhost:7890/draft/my-assistant

  To stop:   muxi down

    Think of muxi up / muxi down like docker compose up / docker compose down - quick start/stop for local development.

  6. Test It

    pip install muxi
    from muxi import FormationClient

client = FormationClient(
    server_url="http://localhost:7890",
    formation_id="my-assistant",
    mode="draft",  # Uses /draft/ prefix for local dev
)

for event in client.chat_stream({"message": "Hello!"}):
    if event.get("type") == "text":
        print(event.get("text"), end="")
    npm install @muxi-ai/muxi-typescript
    import { FormationClient } from "@muxi-ai/muxi-typescript";

const client = new FormationClient({
  serverUrl: "http://localhost:7890",
  formationId: "my-assistant",
  mode: "draft",
});

for await (const event of client.chatStream(
  { message: "Hello!" },
  "user_123"
)) {
  if (typeof event.token === "string") process.stdout.write(event.token);
}
    go get github.com/muxi-ai/muxi-go
    import muxi "github.com/muxi-ai/muxi-go"

client := muxi.NewFormationClient(&muxi.FormationConfig{
    ServerURL:   "http://localhost:7890",
    FormationID: "my-assistant",
    Mode:        "draft",
})

stream, _ := client.ChatStream(ctx, &muxi.ChatRequest{Message: "Hello!"})
for chunk := range stream {
    if token, ok := chunk.Raw["token"].(string); ok {
        fmt.Print(token)
    }
}
    gem install muxi
    require 'json'
require 'muxi'

client = Muxi::FormationClient.new(
  server_url: 'http://localhost:7890',
  formation_id: 'my-assistant',
  mode: 'draft',
  client_key: 'fmc_...'
)

client.chat_stream({ message: 'Hello!' }, user_id: 'user_123') do |event|
  next unless event['event'] == 'message'
  data = JSON.parse(event['data'])
  print data['token'] if data['token'].is_a?(String)
end
    implementation("org.muxi:muxi-java:0.20260212.0")
    FormationClient client = new FormationClient(
    "http://localhost:7890",
    "my-assistant",
    "fmc_...",
    null,
    30,
    "draft"
);

JsonObject request = new JsonObject();
request.addProperty("message", "Hello!");
client.chatStream(request, "user_123", event -> {
    if ("message".equals(event.event())) {
        JsonObject data = JsonParser.parseString(event.data()).getAsJsonObject();
        if (data.has("token")) System.out.print(data.get("token").getAsString());
    }
});
    implementation("org.muxi:muxi-kotlin:0.20260212.0")
    val client = FormationClient(FormationConfig(
    serverUrl = "http://localhost:7890",
    formationId = "my-assistant",
    mode = "draft",
    clientKey = "fmc_..."
))

client.chatStream(
    mapOf("message" to "Hello!"),
    userId = "user_123"
).collect { event ->
    if (event.event == "message") {
        val token = Json.parseToJsonElement(event.data)
            .jsonObject["token"]?.jsonPrimitive?.contentOrNull
        if (token != null) print(token)
    }
}
    // Package.swift
.package(url: "https://github.com/muxi-ai/muxi-swift.git", from: "0.1.0")
    let client = try FormationClient(config: FormationConfig(
    formationId: "my-assistant",
    serverUrl: "http://localhost:7890",
    clientKey: "fmc_...",
    mode: "draft"
))

for try await event in await client.chatStream(
    ["message": "Hello!"],
    userId: "user_123"
) {
    guard event.event == "message",
          let data = event.data.data(using: .utf8),
          let payload = try JSONSerialization.jsonObject(with: data) as? [String: Any],
          let token = payload["token"] as? String else { continue }
    print(token, terminator: "")
}
    dotnet add package Muxi
    using System.Text.Json;

var client = new FormationClient(new FormationConfig
{
    ServerUrl = "http://localhost:7890",
    FormationId = "my-assistant",
    Mode = "draft",
    ClientKey = "fmc_..."
});

await foreach (var evt in client.ChatStreamAsync(
    new Dictionary<string, object> { ["message"] = "Hello!" },
    userId: "user_123"))
{
    if (evt.Event != "message") continue;
    using var document = JsonDocument.Parse(evt.Data);
    if (document.RootElement.TryGetProperty("token", out var token) &&
        token.ValueKind == JsonValueKind.String)
        Console.Write(token.GetString());
}
    composer require muxi/muxi-php
    $client = new FormationClient([
    'serverUrl' => 'http://localhost:7890',
    'formationId' => 'my-assistant',
    'mode' => 'draft',
    'clientKey' => 'fmc_...',
]);

$client->chatStream(
    ['message' => 'Hello!'],
    'user_123',
    function (array $event): void {
        if ($event['event'] !== 'message') return;
        $data = json_decode($event['data'], true);
        if (is_string($data['token'] ?? null)) echo $data['token'];
    }
);
    dart pub add muxi
    final client = FormationClient(FormationConfig(
  serverUrl: 'http://localhost:7890',
  formationId: 'my-assistant',
  mode: 'draft',
  clientKey: 'fmc_...',
));

await for (final event in client.chatStream(
  {'message': 'Hello!'},
  userId: 'user_123',
)) {
  if (event.event != 'message') continue;
  final data = jsonDecode(event.data);
  if (data['token'] is String) stdout.write(data['token']);
}
    cargo add muxi-rust
    let mut config = FormationConfig::new(
    "http://localhost:7890",
    "my-assistant",
    "fmc_...",
    "",
);
config.mode = "draft".to_string();
let client = FormationClient::new(config)?;

let stream = client.chat_stream(json!({"message": "Hello!"}), Some("user_123"));
futures::pin_mut!(stream);
while let Some(event) = stream.next().await {
    let event = event?;
    if event.event == "message" {
        let data: serde_json::Value = serde_json::from_str(&event.data)?;
        if let Some(token) = data["token"].as_str() { print!("{}", token); }
    }
}
    #include <muxi/muxi.hpp>

muxi::FormationConfig config;
config.server_url = "http://localhost:7890";
config.formation_id = "my-assistant";
config.mode = "draft";
config.client_key = "fmc_...";
muxi::FormationClient client(config);

client.chat_stream({{"message", "Hello!"}}, "user_123", [](const auto& event) {
    if (event.event != "message") return;
    auto data = nlohmann::json::parse(event.data);
    if (data.contains("token") && data["token"].is_string())
        std::cout << data["token"].get<std::string>();
});
    curl -X POST http://localhost:7890/draft/my-assistant/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!"}'

    Local dev → Production: Use mode="draft" with muxi up, then remove it after muxi deploy to use the live /api/ endpoint.

Start from Registry

Pull a pre-built formation instead of creating from scratch:

muxi pull @muxi/hello-muxi
cd starter-assistant
muxi secrets setup
muxi up

Browse registry.muxi.org to discover community formations.

What You Built

graph LR
    A[Your App] -->|HTTP/SDK| B[MUXI Server :7890]
    B --> C[Formation :8001]
    C --> D[Agent: assistant]
    D --> E[OpenAI GPT-5]

You now have:

  • A MUXI Server managing formations
  • A Formation with one agent
  • An API ready for integration

Want to understand how this all works? See How MUXI Works for the full architecture and request flow.

Common First Issues

Port already in use
# Find what's using the port
lsof -i :7890

# Use a different port
muxi-server --port 7891
Command not found after install

Restart your terminal, or check your PATH:

# macOS/Linux
echo $PATH | grep -E "(homebrew|local/bin)"

# Add to PATH if needed
export PATH="$PATH:/usr/local/bin"
Server won't start
# Check if already running
ps aux | grep muxi-server

# View logs
muxi-server logs
API key errors
# Verify secret is set
muxi secrets get OPENAI_API_KEY

# Re-run setup
muxi secrets setup

For more issues, see the Troubleshooting Guide.

Next Steps

Deploy to Production

Move beyond localhost to a real server.

Add Tools

Give your agent web search, file access, and more.

Add Memory

Make conversations persist across sessions.

Formation Reference

Complete YAML configuration guide.
Home Docs SDKs
Star on GitHub