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

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. Binding it to the network exposes the agent runtime, including shell execution, to anyone who can reach the port. Read Security first.

If a small trusted team shares one machine, run the gateway on it explicitly:

MUAZ_GATEWAY_TOKEN="$(openssl rand -hex 32)" \
  muaz gateway --host 0.0.0.0

The token is mandatory in practice. Without MUAZ_GATEWAY_TOKEN (or --token) muaz generates one and prints it at startup, which is easy to miss — set it yourself so you know what it is. Every /api request requires it.
Put it behind your own TLS and auth. muaz does not terminate TLS; front it with a reverse proxy.
Add --readonly for an auditor or demo instance that can browse config, sessions, and the audit log but cannot run agents or change anything.

One ~/.muaz/ is one person’s state, so this shape suits a shared machine, not many separate users. To give each person their own partitioned state, Deployment settings covers MUAZ_STORE, per-user MUAZ_SCOPE, and pinning the settings users must not be able to loosen.

First run

Running muaz for the first time bootstraps ~/.muaz/ with sensible defaults — a global config, the built-in agents and the code-review pipeline, and an empty plugins/local/ workspace of your own. You will be up and running once you configure a provider API key (see Quick start).

Nothing else is installed on your behalf. Everything beyond the built-ins — the coding agent included — arrives through a plugin you install and approve, so the list of things running with your credentials is always one you chose.

The `~/.muaz/` directory

See Configuration for the full layout. The short version: config files at the root, your own authored content in plugins/local/, and installed plugins beside it. The read-only built-ins ship inside the binary.

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.