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 (a single extension), not .md.ai: macOS reads a trailing .ai as an Adobe Illustrator file, so foo.md.ai would be misclassified as binary artwork by Finder and editors. .mdai stays plain text everywhere.

File format

YAML frontmatter declares the connections and an optional model; the markdown body is the node's synthesis prompt.

---
sources:
  - path: notes/meeting.md
    prompt: Extract the decisions and open questions from this note.
  - path: research.mdai
    prompt: Use this synthesized research as background.
model: claude-haiku-4-5   # optional per-file override
---
# Weekly brief
Write a five-line brief that states each decision and the single most
important open question, using only the connected sources.

• sources is a list of connections, each {path, prompt}. path is a file, a folder (expanded to its files, size-capped), another .mdai file resolved relative to the containing .mdai file's directory, or the live amux source amux:messages?days=N&limit=N&offset=N. prompt is the configurable edge prompt; a sensible default is filled in when a connection is created without one. A bare string entry (just the path) is also accepted and gets the default prompt.
• amux:messages reads user directives from cmd_history. With no query it uses the last 14 days. days=N is capped at 90. A count window like limit=1000 has no implicit day cutoff, and offset=N pages backward from the newest message; rows are rendered oldest-first with MSG-<id> evidence labels.
• model is an optional per-file override.
• The markdown body is the node synthesis instruction. A plain markdown file with no frontmatter is a valid node with no sources.

How opening runs the chain