amux Agent Control Plane
Coordinate, supervise, and recover parallel coding agents from one self-hosted control plane.
Per-dimension scores and reasoning
The evidence shows layered scopes, a default restriction that agents may write only their own worker layer, purpose-specific macOS permissions, confirmation before sending, origin stamps, message ledgers, TLS/token handling, secret scanning, backups, and uninstall behavior that preserves data. Deductions apply because localhost bypasses authentication, the service is exposed to the local network by default, public tunnels rely on unguessable rather than authenticated URLs, the file root may default to HOME, and schedules, loops, and agent tooling can still cause broad external effects. Some permission failures are documented as silent or hanging. Dependencies are centrally declared and some JavaScript versions are pinned, but the supplied files show no vulnerability audit, automated dependency-update control, or supply-chain verification, so dependency_security receives only 1. Unknown publisher identity is not treated as suspicious.
The README, workspace structure, UI tests, and CI workflows generally describe one coherent Rust control plane and show atomic claiming, durable work items, degraded-state handling, recovery, backup verification, and regression guards derived from past failures. Platform prerequisites, systemd/launchd paths, and a non-systemd fallback are documented. Deductions reflect that none of this was executed for the review, herdr integration is explicitly outside CI coverage, missing macOS permissions can fail silently, the cloud deployment still contains a Python image awaiting migration, and licensing descriptions are internally inconsistent. Many errors are precise and actionable, but explicit failure reporting is not reliable on every documented path.
The material thoroughly covers local individual use, multi-agent teams, mobile control, cloud environments, macOS, several Linux variants, multiple model providers, tmux/herdr backends, and a business-facing UI. Capability boundaries clearly distinguish the Rust server, legacy port, public tunnel, model judgment versus automation, core versus optional permissions, and untested herdr integration. The deduction is mainly for trigger precision: schedules, loops, gates, compare-and-swap claiming, and message timing are described and partly tested, but the supplied source does not expose the complete ambiguity and collision rules for natural-language cron, autonomous loops, and replayed messages.
The README provides unusually complete navigation across architecture, primitives, configuration, platforms, CLI usage, permissions, security, migration, naming, and further resources. Installation, upgrades, uninstall behavior, examples, FAQ links, and known limitations are concrete. Compatibility naming between worker/session and group/tag is explicitly stabilized. The principal deduction is licensing: the product is called open source or MIT, while the README badge and LICENSE add the Commons Clause and Cargo metadata says only MIT; the supplied metadata is also NOASSERTION. A changelog and migration records are linked, but their revision-specific contents are not included. Security contact, contribution guidance, and a roadmap establish maintenance paths, though the publisher is unverified and no formal support or update commitment is shown.
A shared board, atomic claiming, origin-stamped messaging, status gates, durable history, recovery, scheduling, mobile control, and model switching provide clear marginal value beyond isolated agent sessions. The CLI, dashboard, auditable artifacts, failure guidance, and mobile/accessibility tests make results highly usable. Cost_benefit is deducted because the single Rust binary and SQLite simplify deployment but the system still needs Rust, tmux, agent CLIs, model consumption, system permissions, and storage operations. The supplied material records real permission-timeout and cloud-disk incidents and provides no broadly generalizable performance or economic measurements.
The evidence frequently names issue/card identifiers, incident dates, machine signatures, API paths, tests, state assertions, and second-connection backup verification. Many structural README claims are corroborated by the Cargo workspace, Playwright tests, and CI controls. It also carefully separates model judgment from automation, mocked boundaries from real integration, read-only checks from explicit live writes, and tested paths from the uncovered herdr integration. Claim_traceability is deducted because several promotional claims, log statistics, and benefits such as dozens of parallel workers remain repository assertions that cannot be traced or independently checked from the supplied excerpts. No tests were executed in this static review.
- Do not expose port 8824 or compatibility port 8822 directly to the internet; localhost is exempt from authentication, and public tunnel URLs are unguessable rather than authenticated.
- Grant Full Disk Access, Messages, iTerm2, or Accessibility only for features actually used. The documentation explicitly says some denied-permission paths can fail silently or hang.
- Treat server.env, auth tokens, service-account material, and connector credentials as sensitive. Pattern-based CI scanning is not a substitute for secret rotation, dependency auditing, or runtime secret management.
- Obtain legal review before adoption: the LICENSE is MIT plus the Commons Clause, conflicting with Cargo's MIT metadata and the MIT/open-source description.
- Schedules, autonomous loops, message replay, and self-healing restarts may repeat or continue external operations. Validate approval gates, idempotency, stop controls, and recovery behavior in an isolated workspace first.
- The herdr path lacks CI integration coverage, and the cloud deployment still has a Python image pending migration. Do not infer equal assurance from tests of the primary Rust path.
What does this agent do, and when should you use it?
amux is a local-first, self-hosted control plane for running parallel Claude Code, Codex, Gemini CLI, OpenCode, and Ollama workers. Its Rust workspace contains an axum server, an embedded single-page dashboard, the amux-rs CLI, and a shared domain crate, with operational state and an event journal stored in SQLite. Workers run in tmux by default, with an optional herdr backend whose real integration is not covered by CI, and operators can observe or steer sessions through the web dashboard, CLI, or iOS app. The product combines an atomically claimed task board, schedules, autonomous loops, layered memory and environment settings, origin-stamped messaging, model switching, and crash recovery. It is deployed on a user-controlled macOS or Linux machine and serves its API and dashboard at https://localhost:8824 by default; that port is not intended for direct internet exposure.
amux-server-rs starts and manages parallel coding-agent sessions, stores work on a shared board, and uses compare-and-swap claiming so two workers cannot take the same card. Workers can discover same-group peers, inspect peer terminal state, and exchange messages whose true sender is recorded by the server; a human can also type into a running session from the dashboard or phone. Its scheduler runs one-shot jobs, cron-style prompts, and self-paced loops, while the watchdog can compact context, restart crashed sessions, and replay the last message. The server also browses, edits, and searches worker files and executes .mdai computed-Markdown DAGs: POST /api/files/mdai/run resolves dependencies upstream-first, invokes the configured helper model, reuses matching input hashes, and records run history. Every /api request enters a structured request log, the dashboard receives SSE and delta-sync updates, and amux-rs exposes board, workers, send, schedules, and health operations.
- An engineering team working on several features can let parallel Claude Code, Codex, or Gemini CLI workers atomically claim cards from one board and require peer review before moving work from done to verified.
- A solo developer running unattended overnight work can combine schedules such as every 15m or daily at 9am with autonomous loops and watchdog recovery.
- A self-hosting user who needs mobile oversight can inspect workers through the dashboard or iOS app and redirect a live task without stopping the session.
- A team that needs an auditable coordination trail can retain server-authenticated message origins, full message history, event records, and completion evidence.
- A user producing recurring briefs from files and prior directives can build .mdai graphs over regular files, directories, other .mdai nodes, or amux:messages.
- An AI engineering team can select different brains for different jobs by switching the model or provider on a running worker while keeping its context.
What are this agent's strengths and limitations?
- Compare-and-swap task claiming prevents duplicate ownership, while separate done and peer-checked verified states provide an explicit verification gate.
- The server, dashboard, and CLI live in one Rust workspace, and the dashboard is embedded in the server binary without requiring Node.js or npm at build time.
- It coordinates several coding-agent products, supports live model/provider switching, and supplies server-authenticated message provenance, layered scope configuration, and a durable message ledger.
- Long-running fleets get a watchdog, crash restart, last-message replay, structured request logging, and audited scheduler history.
- .mdai composes files, directories, message history, and other nodes into computed DAGs with cycle detection, input-hash caching, and run history.
- Adopters must operate the local server, SQLite state, TLS material, bearer token, and tmux sessions themselves; this is not a maintenance-free hosted service.
- The default deployment uses a self-signed HTTPS certificate, and the documentation explicitly warns against exposing port 8824 directly to the internet.
- The optional herdr backend lacks real CI integration coverage; a successful build proves backend selection, not end-to-end operation.
- Messages, iTerm2, mail, or other automation on macOS may require Automation, Full Disk Access, or Accessibility grants, and missing permissions can cause timeouts or silent failures.
- The stated license is MIT + Commons Clause: modification and self-hosting are allowed, but commercial resale requires a separate license; the supplied repository metadata also reports License as NOASSERTION.
- The Python server and pipx/Homebrew channels are retired, while port 8822 is only a temporary compatibility bind, creating migration work for older installations.
How do you install or deploy this agent?
You need tmux 3.2+ and at least one of Claude Code, Codex CLI, or Gemini CLI. Run:
git clone https://github.com/mixpeek/amux && cd amux && ./install.shThe installer checks the Rust toolchain and tmux, asks before installing missing prerequisites, builds the workspace, installs the server and CLI under ~/.local/bin, and creates ~/.amux with the SQLite database, TLS material, and authentication token on first boot. It configures launchd on macOS. On supported systemd distributions—Ubuntu 22.04+, Debian 11+, and Fedora 36+—finish with:
systemctl --user enable amux-server amux-builder.timer
systemctl --user start amux-serverOn other Linux systems, start it manually with:
AMUX_RS_PORT=8824 ~/.local/bin/amux-server-rsHow do you use this agent?
Open https://localhost:8824, accept the self-signed certificate warning once, and create the first worker in the dashboard. The bearer token is stored at ~/.amux/auth_token, although localhost callers are exempt. Verify the installation with:
amux-rs healthRepresentative commands are:
amux-rs board add "task title" --type code
amux-rs board list --status todo
amux-rs workers list
amux-rs send worker-1 "implement the login endpoint and report back"
amux-rs schedules listTo execute a computed-Markdown node, call:
curl -sk -X POST https://localhost:8824/api/files/mdai/run -H 'Content-Type: application/json' -d '{"path":"weekly.mdai"}'After pulling code, make run rebuilds and reinstalls the release; make dev uses a scratch database for migration or feature work. Use the documented Tailscale route or amux tunnel for remote access instead of exposing port 8824 directly.