Installation

muaz ships as a single pre-built binary. Pick the method that suits your platform — no Rust toolchain required.

Prerequisites

macOS 11 (Big Sur) or later — Apple Silicon and Intel supported
Linux x86_64 or arm64 (glibc 2.17+)
Windows 10 / 11, x64

You will also need an API key from at least one supported provider (OpenAI, Google Gemini, AWS Bedrock) or a locally running Ollama instance. muaz works with any OpenAI-compatible endpoint too.

macOS / Linux — shell installer

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/shigar-dev/releases-muaz/releases/latest/download/muaz-installer.sh | sh

The script installs the binary to ~/.cargo/bin/ and adds it to $PATH if not already present. Restart your terminal after installation.

macOS — Homebrew

brew tap shigar-dev/muaz
brew install muaz

Updates via brew upgrade muaz.

Windows — PowerShell

irm https://github.com/shigar-dev/releases-muaz/releases/latest/download/muaz-installer.ps1 | iex

Windows — MSI installer

Download muaz-x86_64-pc-windows-msvc.msi from the releases page and run it. The installer adds muaz to your PATH.

npm (any platform)

npm install -g @shigar/muaz

Requires Node.js 18+. This installs the same pre-built native binary via npm.

Manual download

Pre-built archives for every platform are on the releases page. Download the archive for your platform, extract the binary, and place it somewhere on your PATH.

Platform	Archive
macOS Apple Silicon	`muaz-aarch64-apple-darwin.tar.xz`
macOS Intel	`muaz-x86_64-apple-darwin.tar.xz`
Linux x86_64	`muaz-x86_64-unknown-linux-gnu.tar.xz`
Linux arm64	`muaz-aarch64-unknown-linux-gnu.tar.xz`
Windows x64	`muaz-x86_64-pc-windows-msvc.zip`

Verify the installation

muaz --version

Docker (team-server mode)

Not the primary way to run muaz. muaz is built to run locally for one person — bare muaz opens the browser UI on 127.0.0.1. The image runs only the gateway, bound to 0.0.0.0 so a small trusted team can share one instance. That exposes the agent runtime (including shell execution) over the network, so a token is mandatory and you should still put it behind your own auth/TLS. Read Security first.

The image is a thin runtime wrapper around a prebuilt Linux muaz binary (which embeds the browser UI). Build the binary, then the image:

cargo build --release -p muaz          # produces target/release/muaz (Linux)
docker build -t muaz-gateway .

docker run --rm -p 7878:7878 \
  -e MUAZ_GATEWAY_TOKEN="$(openssl rand -hex 32)" \
  -v muaz-data:/home/muaz/.muaz \
  muaz-gateway

MUAZ_GATEWAY_TOKEN is required — the container refuses to start without it.
~/.muaz/ (config, sessions, secrets, audit log) persists in the named volume.
Extra muaz gateway flags pass through, e.g. append --readonly for an auditor/demo instance that can browse but not mutate anything.

First run

Running muaz (or muaz chat) for the first time bootstraps ~/.muaz/ with sensible defaults — a global config, a default agent, and a coding agent. You will be up and running once you configure a provider API key (see Quick start).

The `~/.muaz/` directory

After the first run, your home directory contains:

~/.muaz/
├── config.yaml          # global settings (default agent, tool approval policy)
├── agents/
│   ├── default.yaml     # general-purpose agent
│   ├── coding.yaml      # coding-focused agent (auto-bootstrapped)
│   └── my-agent.yaml    # any agent you create with `muaz agents create`
├── prompts/
│   ├── default.md       # system prompt for the default agent (edit freely)
│   └── coding.md        # system prompt for the coding agent (edit freely)
├── skills/
│   └── my-skill/        # Agent Skill directory (each must contain SKILL.md)
│       └── SKILL.md
├── pipelines/
│   └── research-write.yaml   # multi-agent pipeline definitions
├── sessions/
│   ├── index.json       # session index (auto-maintained)
│   └── <uuid>.json      # individual session files
└── commands/
    └── deploy.yaml      # custom slash commands

All paths are configurable — you can point agents at prompts anywhere on disk and reference environment variables with ${ENV_VAR} syntax in YAML configs.

Next: Quick start.