by mixpeek
Open-source control plane for AI coding agents — run, monitor & orchestrate dozens of parallel Claude Code, Codex & Gemini sessions from one web dashboard or your phone. Self-healing, single-file, tmux-native.
# Add to your Claude Code skills
git clone https://github.com/mixpeek/amuxGuides for using ai agents skills like amux.
Last scanned: 5/30/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-30T15:37:34.459Z",
"npmAuditRan": true,
"pipAuditRan": true
}amux is a multi-session agent orchestrator. Run dozens of parallel AI agent workers (Claude Code, Codex, Gemini CLI) from a web dashboard or your phone: a shared kanban board with status gates, schedulers, inter-worker messaging, per-scope memory and environment, browser automation, email, and self-healing recovery. Local-first, self-hosted, SQLite-backed.
amux.io · Getting started · FAQ · Blog
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.
Requirements: macOS (primary; on Linux the installer builds and installs the binaries and prints how to run the server), 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).
License: MIT + Commons Clause — free to use, modify, and self-host. Commercial resale requires a separate license.
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.
One Rust workspace, four crates:
| Crate | What |
|---|---|
crates/amux-server |
The server: axum HTTP API on 8824 (HTTPS, self-signed; plain HTTP redirected), single-writer SQLite store with an event journal, SSE + delta sync, scheduler/orchestrator runtime, embedded dashboard |
crates/amux-dashboard |
The SPA, embedded into the server binary at build time (no node/npm needed) |
crates/amux-cli |
amux-rs, the CLI (board, workers, send, schedules, health) |
crates/amux-core |
Shared domain types: ids, scopes, revisions, memory, protocol |
Everything in amux is built on eight primitives, and new capability is expressed by composing them rather than wrapping them:
done ≠ verified)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:
/api/debug/boundary.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.
Every /api request is recorded in a structured request log (_amux_request_log, served at GET /api/logs and the dashboard's Logs tab; raw server tracing at ~/.amux/logs/server-rs.log; retention AMUX_REQLOG_RETAIN_DAYS, default 14 days).
On top of it sits a daily log sweep: a scheduler entry that prompts a session to run five standing queries (error families, latency p95 vs trailing norm, proxy volume — which must stay zero, auth-failure spikes, and worker-log anomalies), judge the results, and file board cards. The contract lives in docs/rust-migration/log-sweep.md. It is a contract for a model, not an automation: amux supplies the queries and the substrate; the session supplies the judgment.
amux-rs finds the server via --url, then $AMUX_RS_URL, then $AMUX_URL (every running amux session has it), falling back to https://localhost:8824 — the port ./install.sh configures. So a bare invocation just works:
amux-rs health # no env or flags needed
amux-rs board add "task title" --type code
amux-rs board list --status todo
amux-rs board doing PROJ-1
amux-rs board done PROJ-1 --checked "Tests / lint pass" # gates are surfaced loudly, never bypassed silently
amux-rs workers list
amux-rs send worker-1 "implement the login endpoint and report back"
amux-rs schedules list
Board mutations are gate-aware: a 409 from a status gate prints the checklist and the exact retry command instead of failing silently.
Server configuration lives in ~/.amux/server.env (plain KEY=value; process env wins). Highlights:
| Variable | What |
|---|---|
AMUX_RS_PORT |
server port (installer sets 8824) |
AMUX_HOME |
data dir (default ~/.amux) |
AMUX_DB |
SQLite path (default $AMUX_HOME/amux.db) |
AMUX_HERDR_SESSION |
herdr session hosting amux workspaces (enables the herdr backend) |
AMUX_REQLOG_RETAIN_DAYS |
request-log retention (default 14) |
AMUX_SCOPE_WRITE_AGENTS |
1 lets agent sessions write group/global scope layers (default: only their own worker layer) |
server.env.example documents the full set. Never commit your real server.env — several values are secrets.
A worker is one agent lane. A group is a label shared by several workers; workers see and coordinate with same-group peers. The HTTP API and env vars still carry the older session/tag spellings (/api/sessions, X-Amux-Session, CC_TAGS); renaming them would break every running worker at once, so the wire names migrate behind aliases. Worker = session, group = tag, wherever you see them in a request.
Local-first. Auth is a bearer token minted at ~/.amux/auth_token (localhost callers are exempt). Never expose port 8824 to the internet — use Tailscale for phone/remote access, or the amux tunnel for deliberately-public endpoints (tunneled URLs are unguessable, not authenticated). Report vulnerabilities privately per SECURITY.md.
The Python predecessor (
amux-server.py) was removed at commit792ce1f(2026-08-09) — git history has it, and docs/rust-migration/ records how the Rust server replaced it (the Rust binary also answers the legacy 8822, but that bind is a countdown, not an address —GET /api/debug/legacy-portreports who still calls it and when it
amux is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by mixpeek. Open-source control plane for AI coding agents — run, monitor & orchestrate dozens of parallel Claude Code, Codex & Gemini sessions from one web dashboard or your phone. Self-healing, single-file, tmux-native. It has 340 GitHub stars.
Yes. amux passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.
Clone the repository with "git clone https://github.com/mixpeek/amux" and add it to your Claude Code skills directory (see the Installation section above).
amux is primarily written in HTML. It is open-source under mixpeek on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh amux against similar tools.
No comments yet. Be the first to share your thoughts!