Quickstart

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

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 Server 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!" })) {
     if (event.type === "text") process.stdout.write(event.text);
   }

   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 chunk.Type == "text" {
           fmt.Print(chunk.Text)
       }
   }

   gem install muxi

   require 'muxi'
   
   client = Muxi::FormationClient.new(
     server_url: 'http://localhost:7890',
     formation_id: 'my-assistant',
     mode: 'draft'
   )
   
   client.chat_stream(message: 'Hello!') do |event|
     print event['text'] if event['type'] == 'text'
   end

   implementation("org.muxi:muxi-java:0.20260212.0")

   FormationClient client = new FormationClient(
       "http://localhost:7890",
       "my-assistant",
       "draft"
   );
   
   client.chatStream(new ChatRequest("Hello!"), event -> {
       if ("text".equals(event.getType())) {
           System.out.print(event.getText());
       }
       return true;
   });

   implementation("org.muxi:muxi-kotlin:0.20260212.0")

   val client = FormationClient(
       serverUrl = "http://localhost:7890",
       formationId = "my-assistant",
       mode = "draft"
   )
   
   client.chatStream(ChatRequest(message = "Hello!")).collect { event ->
       if (event.type == "text") print(event.text)
   }

   // Package.swift
   .package(url: "https://github.com/muxi-ai/muxi-swift.git", from: "0.1.0")

   let client = FormationClient(
       serverURL: "http://localhost:7890",
       formationID: "my-assistant",
       mode: "draft"
   )
   
   for try await event in client.chatStream(message: "Hello!") {
       if event.type == "text" { print(event.text ?? "", terminator: "") }
   }

   dotnet add package Muxi

   var client = new FormationClient(
       serverUrl: "http://localhost:7890",
       formationId: "my-assistant",
       mode: "draft"
   );
   
   await foreach (var chunk in client.ChatStreamAsync(new ChatRequest { Message = "Hello!" }))
   {
       if (chunk.Type == "text") Console.Write(chunk.Text);
   }

   composer require muxi/muxi-php

   $client = new FormationClient(
       serverUrl: 'http://localhost:7890',
       formationId: 'my-assistant',
       mode: 'draft'
   );
   
   foreach ($client->chatStream(['message' => 'Hello!']) as $event) {
       if ($event['type'] === 'text') echo $event['text'];
   }

   dart pub add muxi

   final client = FormationClient(
     serverUrl: 'http://localhost:7890',
     formationId: 'my-assistant',
     mode: 'draft',
   );
   
   await for (final event in client.chatStream(message: 'Hello!')) {
     if (event['type'] == 'text') stdout.write(event['text']);
   }

   cargo add muxi-rust

   let client = FormationClient::new(
       "http://localhost:7890",
       "my-assistant",
   ).with_mode("draft");
   
   let mut stream = client.chat_stream("Hello!").await?;
   while let Some(event) = stream.next().await {
       if event?.event_type == "text" { print!("{}", event.text.unwrap_or_default()); }
   }

   #include <muxi/muxi.hpp>
   
   auto client = muxi::FormationClient(
       "http://localhost:7890",
       "my-assistant",
       "draft"
   );
   
   client.chat_stream({{"message", "Hello!"}}, [](const auto& event) {
       if (event.type == "text") std::cout << event.text;
       return true;
   });

   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 dev

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]

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

Common First Issues

# Find what's using the port
lsof -i :7890

# Use a different port
muxi-server --port 7891

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

# Add to PATH if needed
export PATH="$PATH:/usr/local/bin"

# Check if already running
ps aux | grep muxi-server

# View logs
muxi-server logs

# 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