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