amux

amux runs coding-agent sessions on a machine. Each session is a named, long-running agent (Claude Code, Codex, Gemini, OpenCode or Antigravity) living inside tmux, with a web dashboard that shows every session at once. It is the per-machine layer of the multi-machine stack : one amux per machine, optionally tied together by hcom .

The amux docs live at amux.nuilab.org

Installing, every command, several Claude subscriptions, driving other machines, the status line and troubleshooting are documented once, next to the code, at amux.nuilab.org (opens in new tab) . This page covers where amux fits in an agent setup; the details are kept there so they never drift apart.

Why it matters for agents

Persistence. Sessions live in tmux, so an agent keeps working after you detach, close the terminal, or drop the SSH connection. Reattach later, right where it was.
Many agents, one view. amux ls lists every session and whether it is running; amux peek shows the last lines without attaching; amux send types a prompt into one.
Context is not lost on restart. A restarted session resumes its newest real conversation instead of starting blank. Find and resume the right conversation covers picking a different one.
Several machines. From one laptop, amux -H <box> drives another machine’s sessions and amux -A lists them all. See Connect machines .
Several subscriptions. Each Claude session can bill a different plan (personal or team); amux ls shows which.

Get it

git clone https://git.nuilab.org/f.ortega/amux-nui-public.git
cd amux-nui-public && ./install.sh && amux-doctor

That installs a ready-to-use build of upstream amux (opens in new tab) plus the companion commands. Tarballs: amux.nuilab.org/download (opens in new tab) . Start with the overview (opens in new tab) .

Providers: which agent a session runs

Each session runs one coding agent, chosen with --provider when it is created: claude, codex, gemini, opencode or agy. The agent’s own flags ride along and are remembered with the session.

opencode is the local-model lane

When a session’s provider is opencode, amux verifies the model endpoint is local — loopback or a private-network address serving Ollama , not a hosted API — and refuses to start otherwise. Point opencode at a model you serve yourself: see opencode and Local and frontier models .

Full access, and the sandbox each agent starts in

Left alone, the agents ask before doing anything consequential, and codex additionally runs its shell inside a sandbox. Switching that off is the agent’s own flag — the last column of the table above — and since register / exec pass unknown flags straight through, it rides on the session:

amux exec build --provider codex --dir ~/src --dangerously-bypass-approvals-and-sandbox
amux exec ui    --provider claude --dir ~/src --dangerously-skip-permissions

The flag is persisted with the session, so every later amux start keeps it. Register the session without it to get the agent’s normal, guarded behavior back.

A middle ground for codex: permission profiles

codex (0.147) reads permission profiles from its config — [permissions.<name>] blocks with per-path read / write / deny rules, extends for a base, and network.enabled — and you select one with -p <name>. That is the setting between “approve every command” and “no sandbox at all”: broad filesystem access for the work, with credential files (~/.ssh, cloud tokens, .netrc, keyrings) explicitly denied.

Two things worth knowing before you write one: extends accepts only :read-only and :workspace — there is no full-access base to subtract from, so you extend :workspace and widen it explicitly — and a narrow read rule does not re-open a path under a denied parent, so a directory holding both secrets and files the agent needs (~/.ssh is the usual one) has to be spelled out file by file rather than denied wholesale.

Two behaviors that trip people up

Remote start attaches only when interactive

From a terminal, amux-remote BOX start NAME starts (or no-ops on) the session on that box and then attaches you over SSH. From a script, a pipe, or with --no-attach, it starts only and prints the attach command instead — so automation never grabs your terminal. amux-remote BOX attach NAME attaches on its own at any time.

codex has no --effort flag

Reasoning effort on codex is a config override, not a flag: -c model_reasoning_effort=medium. Plain codex --effort medium fails with unexpected argument '--effort' found (0.147), and so does codex resume. Since amux puts your flags on the agent’s command line verbatim, a codex session registered with --effort dies the moment it launches — with the agent’s error, not amux’s. Register it with -c model_reasoning_effort=<low|medium|high> instead.

--continue is dropped on an already-running session

amux start NAME --continue only takes effect when the session is not already running. If it is, start short-circuits to “attach” and silently drops the flag. Stop it first, or resume from inside the session with the agent’s own --resume.

The full amux docs: amux.nuilab.org (opens in new tab) .
Hands-on from scratch: Run agents on one machine .
Tie machines together: hcom and Connect machines .
Quick lookups: the amux cheat sheet .

Source: content/tools/amux.md · maintained in the nuilab-agenticai repository.