amux

amux is the open-source control plane for AI coding agents. Run an AI engineering team: dozens of parallel workers (Claude Code, Codex, Gemini CLI, OpenCode, Ollama) coordinated from one web dashboard or your phone. Local-first, self-hosted, SQLite-backed, one Rust binary.

What the fleet gets that a single agent never had:

• Atomic tasks: a shared kanban board where claiming is compare-and-swap, so two workers can never grab the same card; done requires evidence, verified requires a peer check
• Worker awareness: every worker sees the fleet (who is live, what they own, what they are doing) and can peek into any peer's terminal before interrupting
• @ each other: origin-stamped inter-worker messaging; the server records the true sender, so provenance is a fact rather than a claim
• Steering: type into any running session from the dashboard or phone; redirect mid-task without stopping the run
• Schedules & loops: cron-style recurring prompts (daily at 9am, every 15m) plus self-pacing autonomous loops for overnight runs
• Groups & scope: workers organize into lanes that share memory, environment, and gates; settings resolve card → worker → group → global
• Model switching: swap the model or provider on a running worker; pick the brain per task, keep the context
• Message history: every prompt, reply, and delivery is a ledger row you can fetch later
• Self-healing: a watchdog that auto-compacts, restarts crashed sessions, and replays the last message

amux.io · Getting started · FAQ · Blog

Quickstart — one command

git clone https://github.com/mixpeek/amux && cd amux && ./install.sh

That is the whole setup. The installer checks prerequisites (Rust toolchain, tmux; it prompts before installing anything), builds the workspace, installs the server and CLI to ~/.local/bin, loads the launchd agents on macOS, mints ~/.amux (DB, TLS, auth token) on first boot, waits for /health, and prints:

Dashboard   https://localhost:8824
Auth token  ~/.amux/auth_token
CLI         amux-rs --url https://localhost:8824 health

Open https://localhost:8824, accept the self-signed cert warning once, and add your first worker from the dashboard. Re-running ./install.sh upgrades in place and never touches your data; ./uninstall.sh removes the binaries and agents and leaves ~/.amux alone.

After first install

Once installed, day-to-day commands are short:

make run        # rebuild + reinstall; the running server self-adopts in ~5s
make dev        # run against a scratch DB (safe for testing migrations)
make status     # launchd + /health at a glance
make restart    # kick the launchd-managed server
make check      # cargo check + JS syntax (fast, no link)
make test       # clippy + cargo test

make run is the command after git pull — it rebuilds release, installs the binary, and the launchd-managed server picks it up automatically. make dev is for working on migrations or features you don't want touching the live DB.

Requirements: tmux 3.2+, and at least one of Claude Code, Codex CLI, or Gemini CLI. The Rust toolchain is installed via rustup if you don't have it (with your confirmation).

Linux: systemd user services

On Linux with systemd (Ubuntu 22.04+, Debian 11+, Fedora 36+), ./install.sh automatically creates and enables three user-level services:

• amux-server.service — the main server
• amux-builder.service — auto-rebuild on code changes
• amux-builder.timer — periodic rebuild check (every 60s)

After ./install.sh completes, the services are ready to start:

systemctl --user enable amux-server amux-builder.timer
systemctl --user start amux-server

View logs and status:

journalctl --user -u amux-server -f      # follow logs
systemctl --user status amux-server      # service status

See docs/systemd-setup.md for complete documentation: troubleshooting, multi-user setup, environment overrides, and migration between versions.

For other Linux distributions without systemd, run the server manually:

AMUX_RS_PORT=8824 ~/.local/bin/amux-server-rs

Platform support:

• macOS (primary) — ./install.sh sets up launchd agents for automatic startup and rebuild
• Linux (systemd) — ./install.sh creates systemd user services (Ubuntu 22.04+, Debian 11+, Fedora 36+)
• Other Linux — ./install.sh builds and installs binaries; run the server manually or wrap in your process manager

License: MIT + Commons Clause — free to use, modify, and self-host. Commercial resale requires a separate license.

Which server is real?

The Rust server (crates/amux-server, port 8824). That is what ./install.sh installs, what the dashboard talks to, and where all new work lands. Every /api family answers natively; the live proof is GET /api/debug/boundary, which reports proxied: []. If you are reading code, start in crates/ — it is the only server code in the tree. The same binary also answers the retired port 8822 while a compatibility bind survives (see Legacy), so there is no second server to reason about; the Python predecessor is gone.

Architecture

One Rust workspace, four crates:

Everything in amux is built on eight primitives, and new capability is expressed by composing them rather than wrapping them:

• board — shared kanban with atomic claiming, types, and status gates (done ≠ verified)
• workers — parallel agent sessions (tmux by default), each with durable identity
• schedulers — cron-style recurring and one-shot jobs with an audited run history
• filesystem — browse/edit/search any worker's working directory; file viewer + media pipeline
• groups — tags on workers; scoping for visibility, gates, memory, and env (workers see same-group peers)
• memories — layered instructions/knowledge composed global → group → worker
• environment — layered env vars the same way (which 3p APIs a worker can reach)
• messages — inter-worker and human-to-worker text, delivered at turn boundaries

The uniform way to read/write per-scope configuration (memory, rules, env, board gates, status availability at global/group/worker level) is one endpoint: GET/PUT /api/scope.

Useful pointers:

• Server boundary / migration status: docs/rust-migration/server-boundary.md — the full ownership matrix (all families RUST-NATIVE, zero proxied) and the contract subtleties, cross-checked by tests and served live at /api/debug/boundary.
• Cutover runbook: docs/rust-migration/cutover-runbook.md — the gates for retiring the Python server.
• Rebuild plan: docs/rust-rebuild-plan.md.

Terminal backends: tmux, herdr, and the structured protocol

tmux is the default and fully supported backend. Sessions can instead run on herdr: set AMUX_HERDR_SESSION=<herdr session name> in ~/.amux/server.env (the herdr session that hosts amux workspaces; workers opt in per-session with CC_BACKEND=herdr). The herdr path is not covered by CI (its tests mock the process boundary), so treat a green build as proving backend selection, not the integration.

Longer term, terminal scraping is the fallback, not the plan: the opencode module (crates/amux-server/src/opencode/) defines the structured AgentProtocol through which prompts, messages, cancellation, and state queries flow directly, shrinking the scraper to a liveness check as coverage grows.

Computed files: .mdai

A .mdai file is a computed markdown file: a node in a directed acyclic graph (DAG) whose value is produced by a model. It composes two existing primitives, the filesystem and the model over linked files, and adds no new subsystem. A node connects to source files, folders, or other .mdai files through per-connection prompts (the edges), and its markdown body is the instruction that synthesizes those sources into the node's output. Opening a node runs its whole upstream chain and populates the output.

The extension is `.mdai