Skip to content
shigar muaz

Quick start

  1. Set a provider API key.

    Terminal window
    export OPENAI_API_KEY=sk-...

    Or skip the export and store the key with muaz — run muaz auth (or /auth inside a chat session), or use the browser UI’s Providers page. It’s saved to your OS keychain and used automatically. See API keys & authentication.

    muaz supports OpenAI-compatible endpoints, Google Gemini, AWS Bedrock, and local Ollama. Agents are model-agnostic — define a provider profile once and set it as the default to use it everywhere. See Providers & models.

  2. Open the browser UI.

    Terminal window
    muaz                             # bare command → starts the gateway + opens the UI

    Bare muaz is web-first: it starts a local gateway on 127.0.0.1:7878 and opens your browser (over SSH / no tty it prints the URL instead). A first-run wizard walks you through picking a provider, pasting a key, and dropping into your first chat. From there you get agents, pipelines, connectors, skills, and settings — all in one place. See Browser UI.

  3. Prefer the terminal? Use the REPL.

    Terminal window
    muaz chat                        # chat with the default agent in the terminal
    muaz chat --agent coding         # open the built-in coding agent
    muaz chat --incognito            # don't save the session to disk
    muaz chat --session <id>         # resume a previous session by ID

    The REPL is the power-user surface. Type /help for every slash command:

    CommandDescription
    /helpShow all commands
    /agentsList available agents
    /switch <name>Load a different agent
    /toolsList tools and their approval policy
    /sessionsBrowse and resume recent sessions
    /usageToken and latency stats for this session
    /exitQuit muaz

Run a one-off turn (scripting)

Section titled “Run a one-off turn (scripting)”

muaz run sends a single turn to an agent and prints the result — no REPL, no interactive session. It reads from stdin when piped, making it easy to wire into shell scripts or editor workflows.

Terminal window
# Ask a question directly
muaz run "what is the difference between a mutex and a semaphore?"


# Pipe context in alongside the prompt
git diff | muaz run "review this change and flag any bugs"


# Summarise a file
muaz run "summarise this" < README.md


# Get structured JSON output (includes usage stats and tool calls)
muaz run "list the files here" --output json

Server mode

Section titled “Server mode”

muaz gateway runs the same web server without auto-opening a browser — for headless boxes, or a small trusted team sharing one instance (see the Docker team-server image).

Terminal window
muaz gateway                 # server mode: prints the URL, no browser open
muaz gateway --readonly      # auditors/demos: browse, but no state changes

See Browser UI and Security.

What next?

Section titled “What next?”
  • Guides — four end-to-end walkthroughs of the flagship workflows (coding agent, pipelines, your-data/RAG, connector automation).
  • Connectors — add GitHub, filesystem, fetch, memory, and Linear in a couple of clicks.

Where to go next

Section titled “Where to go next”