cmux-cloud-vm

Source excerpt starting at line 1.

1# Agent workflows on cmux Cloud machines2 3Recipes for doing the user's work *on* a machine while keeping the user in the loop. All of them assume `cmux auth status` reports signed-in.4 5## 0. Decide and route (every task starts here)6 7```bash8cmux vm route --json                  # {machine, created, reason, would_provision}9cmux vm tree                          # what is already running where (terminals, agents, open panes)10```11 12- Reuse the routed machine when `would_provision` is false — its checkout and deps are warm.13- `would_provision: true` means a new machine slot; check `cmux vm ls` (plan meter, free window) and prefer Base or an idle machine before creating.14- Long-running or interactive work → `vm agent` / a session terminal, not `exec`.15 16## 1. Cloud dev box from the local repo ("set it up like magic")17 18```bash19cmux vm run --sync -- bun install                                # --sync runs inside the synced work/<dir>20# idempotent dev server with a workspace-scoped pidfile/log21cmux vm run --sync -- sh -c 'pid=$(cat .cmux-dev.pid 2>/dev/null); if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null && netstat -tlnp 2>/dev/null | grep -q ":3000 .*[ /]$pid/"; then echo "dev server already up (pid $pid owns :3000)"; else rm -f .cmux-dev.pid .cmux-dev.log; if netstat -tln 2>/dev/null | grep -q ":3000 "; then echo "port 3000 is owned by another process" >&2; exit 1; fi; nohup bun run dev > .cmux-dev.log 2>&1 & echo $! > .cmux-dev.pid; fi'22cmux vm run --sync -- sh -c 'for i in $(seq 1 60); do wget -qO- http://localhost:3000 >/dev/null 2>&1 && exit 0; sleep 1; done; tail -n 20 .cmux-dev.log; exit 1'23id=$(cmux vm route --json | jq -r '.machine')                    # the machine the router bound24cmux vm open "$id":port/3000 --print                             # private-network URL to give the user (resolves only on a Mac with `cmux vpn up`)25```26 27Sticky binding means every `vm run` from this directory lands on the same machine. The explicit reuse-or-create spelling still works when you want full control:28 29```bash30# After provisioning is authorized, use the router's recorded pool IDs.31id=$(cmux vm route --provision --json | jq -er '.machine')32cmux vm wait "$id" --wake33cmux vm push "$id" . work/app34cmux vm exec "$id" -- sh -c 'cd work/app && bun install'35```36 37Finish with `cmux notify --title "Cloud dev server up" --body "<url>"`.38 39## 2. Hand a task to an agent on the machine40 41```bash42term=$(cmux vm agent --agent claude --sync --json -- "run the test suite, fix failures, commit on a branch" )43echo "$term" | jq -r '.reattach'                                  # cmux vm open <machine>/<ws>/<term>44cmux vm tree "$(echo "$term" | jq -r '.machine')"                 # [agent claude running] … (open: surface:N)45```46 47The agent runs as a detached terminal in the machine's cmux-tui session: it keeps going if the pane closes, and `cmux vm open <reattach address>` brings it back (reusing the pane if one already shows it). Fan out by calling `vm agent` once per task with `--machine` pinned to different machines (or forks, §4) and watch them all in `cmux vm tree`.48 49Inside the machine the agent authenticates like it would locally (its own login, or CodeRouter's env/config under the remote `$HOME`, set once with `vm exec`). Never copy the user's tokens onto a machine unless they ask.50 51## 2b. Drive an interactive program headlessly (REPL, TUI, watch mode, another agent)52 53```bash54out=$(cmux surface new-terminal --machine <id> --no-open --json -- sh -lc 'cd "$HOME/work/app" && exec bun test --watch')55term=$(echo "$out" | jq -r '.terminal_id')56cmux vm terminal wait <id> "$term" --pattern 'Waiting for file changes|passed|failed' --timeout 30057cmux vm terminal read <id> "$term"                                # the screen a person would see58cmux vm terminal send <id> "$term" --keys ctrl+c                  # stop it; `send … 'text' --keys enter` types a line59cmux vm terminal close <id> "$term"                               # done with it60```61 62No pane is attached and no focus moves; a pane the user already has on that terminal shows the same input. `terminal wait` exits 1 on timeout with the screen tail, so branch on it rather than sleeping.63 64## 3. Repo with history (private repos, no credentials on the machine)65 66```bash67git bundle create /tmp/repo.bundle --all68cmux vm push <id> /tmp/repo.bundle work/repo.bundle69cmux vm exec <id> -- sh -c 'cd work && git clone repo.bundle app && cd app && git checkout main'70```71 72Public repos can just clone on the machine: `cmux vm exec <id> -- git clone https://github.com/org/repo work/repo`.73 74## 4. Builds and tests in the cloud instead of the local Mac75 76```bash77run=test-$(uuidgen | tr 'A-Z' 'a-z' | cut -c1-8)78cmux vm exec <id> -- sh -c "cd work/app && rm -f /tmp/$run.log /tmp/$run.status && nohup sh -c 'make test > /tmp/$run.log 2>&1; echo \$? > /tmp/$run.status.tmp && mv /tmp/$run.status.tmp /tmp/$run.status' >/dev/null 2>&1 &"79cmux vm exec <id> -- sh -c "cat /tmp/$run.status 2>/dev/null || echo running"   # poll; status appears atomically when done80# or skip the pidfile dance: `cmux vm run --machine <id> --timeout 900 -- sh -c 'cd work/app && make test'` blocks up to 15 min and passes the exit code through81cmux vm exec <id> -- tail -n 30 /tmp/$run.log82cmux vm pull <id> work/app/dist ./dist-from-cloud83```84 85Report the real outcome from the log — a finished poll is not a passed test.86 87## 5. Parallel experiments with checkpoints and forks88 89```bash90cmux vm snapshot <id> --name pre-experiment91fork_a=$(cmux vm fork <id> --name try-approach-a --detach --json | jq -r '.id')92fork_b=$(cmux vm fork <id> --name try-approach-b --detach --json | jq -r '.id')93cmux vm agent --agent codex --machine "$fork_a" --no-open -- exec "try approach A in work/app"94cmux vm agent --agent codex --machine "$fork_b" --no-open -- exec "try approach B in work/app"95cmux vm tree                                           # both agents, side by side96```97 98Delete only the forks you created after the experiment (`cmux vm rm <id>`).99 100## 6. Desktop and browser tasks101 102New machines (`cmux vm new`) include TigerVNC with an openbox session and noVNC on 6901; shells get `DISPLAY=:1` while the desktop is up. Drive it from inside the machine (`vm agent` with a computer-use-capable agent — `cua-driver` is preinstalled) and show the human the screen. Historical shell-only machines still have no screen; inspect `vm status` before opening one:103 104```bash105cmux vm open <id>:desktop              # the screen as a browser pane beside the shell106cmux vm exec <id> -- sh -c 'DISPLAY=:1 xdotool key ctrl+l'   # quick desktop pokes107```108 109## 6b. Stage a workspace the user opens later ("it just appears")110 111Group one task's terminals into a named machine workspace, so the whole thing opens with one click of its sidebar row (or one `vm workspace open`) — on this Mac now, or any signed-in Mac after the laptop was closed:112 113```bash114ws=$(cmux vm workspace new <id> --name pr-4123 --json | jq -r '.remote_workspace_id')115cmux surface new-terminal --machine <id> --remote-workspace "$ws" --no-open --name dev   -- sh -lc 'cd "$HOME/work/app" && exec bun run dev'116cmux surface new-terminal --machine <id> --remote-workspace "$ws" --no-open --name tests -- sh -lc 'cd "$HOME/work/app" && exec bun test --watch'117cmux surface new-terminal --machine <id> --remote-workspace "$ws" --no-open --name agent -- sh -lc 'cd "$HOME/work/app" && exec claude -p "fix the failing tests"'118cmux vm tree <id> --json                          # verify the composition headlessly: terminals, lifecycle, agent state119cmux notify --title "Cloud workspace staged: pr-4123" --body "Open: click the pr-4123 row, or cmux vm workspace open <id> $ws"120```121 122- The staged workspace lives on the machine. Its terminals keep running with every pane closed and the Mac asleep; opening it later shows one pane per live terminal.123- `vm workspace new` also opens a new **local** workspace as a side effect; when staging for later, close that local workspace — the machine workspace and its terminals stay (closing panes never kills machine terminals).124- `vm agent` cannot target a workspace; when the agent's terminal should live in the staged workspace, start it with `surface new-terminal --remote-workspace` and a login shell (`sh -lc '…'`) as above. A plain `vm agent --machine <id> --no-open` works too — its terminal just lands outside the staged group.125- Watch progress without opening anything: `cmux vm terminal read <id> <term>`, or block on a result with `terminal wait --pattern`.126 127## 6c. Publish a service for a person to open128 129Use a domain publication when the result must be reachable over HTTPS outside the130owner's private tunnel. Keep `vm open <id>:port/<n>` for private previews; it is131not a shareable public URL.132 133```bash134# 1. Confirm the VM and port, then create a generated cmux hostname.135cmux vm status <id>136cmux vm ports <id>137publication=$(cmux cloud domains publish <id> 3000 --access personal --json)138echo "$publication" | jq -r '.publication.url'139 140# 2. For a custom zone, start/continue verification and follow every record shown.141cmux cloud domains verify example.com142# Add the ownership TXT, apex/wildcard routing, and _acme-challenge NS records,143# wait for DNS propagation, then run the same verify command again.144cmux cloud domains publish <id> 3000 --domain app.example.com --access team --team <team-id>145 146# 3. Check activation and hand off only the URL and intended policy.147cmux cloud domains list --json | jq '.publications[] | {url,hostname,accessMode,state,verification}'148cmux notify --title "Cloud preview ready" --body "Open the URL from cmux cloud domains list"149```150 151`personal` is the default and requires the publication owner to sign in; `team`152requires a current member of the selected team and a `--team` id; `public` permits153anyone with the URL. `cmux cloud domains access` changes that policy and `rm`154unpublishes it. A custom zone is verified once and can then serve its apex or a155single-label child; a generated cmux hostname needs no customer DNS records. Do156not paste a public URL into logs or agent prompts unless the user intentionally157chose `public`.158 159## 7. Showing the human160 161```bash162cmux vm tree <id>                      # the map: which terminal is which, what is already open163cmux vm open <id>/<ws>/<term>          # one terminal as a pane (reuses an open pane)164cmux vm open <id>                      # shell (+ screen on desktop machines)165cmux vm open <id>:desktop              # the screen166cmux vm open <id>:port/3000            # the app they should look at, as a browser pane (private network; `cmux vpn up`)167cmux vm handoff <id>                   # attach block another human/agent can follow168```169 170Pair with `cmux notify` so they know why a pane appeared. Prefer `--print`/`--detach`/`--no-open` until the moment you intend the user to look; `vm open` never steals focus unless `--focus true`.171 172## 8. Cleanup etiquette173 174- New cmux-created machines normally remain available until explicitly paused or stopped; older/provider-managed machines may sleep. Opening or running a command wakes a sleeper, so leaving one for the user to inspect is fine (say so in your handoff).175- Delete forks and scratch machines you created once their purpose is served; close the workspaces and terminals you opened on a shared machine (`vm terminal close`, `vm workspace rm`).176- Never `vm rm` or `vm base reset` a machine you didn't create without explicit user confirmation — `vm rm` deletes it permanently; `vm base reset` creates a new Base generation and retains the old machine.177# Agent workflows on cmux Cloud machines178 179Recipes for doing the user's work *on* a machine while keeping the user in the loop. All of them assume `cmux auth status` reports signed-in.180 181## 0. Decide and route (every task starts here)182 183```bash184cmux vm route --json                  # {machine, created, reason, would_provision}185cmux vm tree                          # what is already running where (terminals, agents, open panes)186```187 188- Reuse the routed machine when `would_provision` is false — its checkout and deps are warm.189- `would_provision: true` means a new machine slot; check `cmux vm ls` (plan meter, free window) and prefer Base or an idle machine before creating.190- Long-running or interactive work → `vm agent` / a session terminal, not `exec`.191 192## 1. Cloud dev box from the local repo ("set it up like magic")193 194One verb does the whole thing when the project has a recognizable dev command:195 196```bash197cmux vm dev <id>                       # route → optional push → detect command/port → layout apply --name → open geometry on the Mac198cmux vm dev <id> --port 3000 --name app   # override the detected port and workspace name199cmux vm dev <id> --no-open                # stage the workspace; print `vm workspace open` instead of opening a local pane200cmux vm dev <id> --dry-run --json         # inspect the plan without socket traffic201cmux vm push <id> . work/app --watch   # in a second terminal: keep the machine in sync while you edit locally202```203 204By hand, the same steps as separate primitives (use these when the dev command needs a pidfile, a database, or a seed step). For a layout, use `vm layout apply --name`; do not create a starter-shell workspace with `vm workspace new --no-open` and then expect it to be empty:205 206```bash207cmux vm run --sync -- bun install                                # --sync runs inside the synced work/<dir>208# idempotent dev server with a workspace-scoped pidfile/log209cmux vm run --sync -- sh -c 'pid=$(cat .cmux-dev.pid 2>/dev/null); if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null && netstat -tlnp 2>/dev/null | grep -q ":3000 .*[ /]$pid/"; then echo "dev server already up (pid $pid owns :3000)"; else rm -f .cmux-dev.pid .cmux-dev.log; if netstat -tln 2>/dev/null | grep -q ":3000 "; then echo "port 3000 is owned by another process" >&2; exit 1; fi; nohup bun run dev > .cmux-dev.log 2>&1 & echo $! > .cmux-dev.pid; fi'210cmux vm run --sync -- sh -c 'for i in $(seq 1 60); do wget -qO- http://localhost:3000 >/dev/null 2>&1 && exit 0; sleep 1; done; tail -n 20 .cmux-dev.log; exit 1'211id=$(cmux vm route --json | jq -r '.machine')                    # the machine the router bound212cmux vm open "$id":port/3000 --print                             # tokened URL to give the user213```214 215Sticky binding means every `vm run` from this directory lands on the same machine. The explicit reuse-or-create spelling still works when you want full control:216 217```bash218id=$(cmux vm ls --json | jq -r '[.vms[] | select(.displayName == "agent-pool" and (.status | test("^(running|ready|standby|paused)$")))][0].id // empty')219[ -n "$id" ] || id=$(cmux vm new --base --detach --json | jq -r '.id')220cmux vm wait "$id" --wake221cmux vm push "$id" . work/app222cmux vm exec "$id" -- sh -c 'cd work/app && bun install'223```224 225Finish with `cmux notify --title "Cloud dev server up" --body "<url>"`.226 227## 1b. Stage a finished workspace for the human (layout + env + code)228 229The person wants to open one workspace and find everything in place: the checkout, the secrets, an agent pane, a test watcher, the app in a browser pane. Build it headlessly, verify, then open.230 231```bash232id=$(cmux vm route --json | jq -r '.machine')233cmux vm push "$id" . work/app                                         # code (or a git bundle, §3)234cmux vm env set "$id" --from-file .env.cloud                          # secrets: on the machine, never in the layout235cat > /tmp/app-layout.json <<'JSON'236{"name":"app","cwd":"work/app","layout":{"direction":"horizontal","split":0.6,"children":[237  {"pane":{"surfaces":[{"type":"terminal","name":"claude","command":"claude","focus":true}]}},238  {"direction":"vertical","split":0.5,"children":[239    {"pane":{"surfaces":[{"type":"terminal","name":"tests","command":"bun test --watch"},{"type":"terminal","name":"shell"}]}},240    {"pane":{"surfaces":[{"type":"terminal","name":"dev","command":"bun run dev"},{"type":"browser","url":"http://localhost:3000"}]}}]}]}}241JSON242ws=$(cmux vm layout apply "$id" /tmp/app-layout.json --json | jq -r '.workspace_id')243cmux vm tree "$id"                                                     # the panes exist; agents/tests show their state244cmux vm terminal wait "$id" "$(cmux vm tree "$id" --json | jq -r '.resources[] | select(.title=="dev") | .key')" --pattern 'localhost:3000' --timeout 120245cmux vm workspace open "$id" "$ws"                                     # same geometry on the Mac (or: layout apply … --open)246cmux notify --title "Workspace ready: app" --body "cmux vm open $id/$ws"247```248 249Reuse a human's arrangement: `cmux vm layout export <id> <ws> > team-layout.json`, commit it next to the repo, and `cmux vm layout apply <fork> team-layout.json` on every fork. A layout the person saved on the Mac (`cmux layout save dev`) applies in the cloud with `--from-saved dev`.250 251## 2. Hand a task to an agent on the machine252 253```bash254term=$(cmux vm agent --agent claude --sync --json -- "run the test suite, fix failures, commit on a branch" )255echo "$term" | jq -r '.reattach'                                  # cmux vm open <machine>/<ws>/<term>256cmux vm tree "$(echo "$term" | jq -r '.machine')"                 # [agent claude running] … (open: surface:N)257```258 259The agent runs as a detached terminal in the machine's cmux-tui session: it keeps going if the pane closes, and `cmux vm open <reattach address>` brings it back (reusing the pane if one already shows it). Fan out by calling `vm agent` once per task with `--machine` pinned to different machines (or forks, §4) and watch them all in `cmux vm tree`.260 261When you need the result, not the terminal, block until the agent is done and take its output in one call:262 263```bash264cmux vm agent --agent claude --machine <id> --sync --wait --output --timeout 1800 -- "run the suite, fix failures, commit on a branch" > agent.log; echo "exit=$?"265# fan-out: start each without --wait, then wait on the terminals266for t in $t1 $t2 $t3; do cmux vm terminal wait-exit <id> "$t" --timeout 1800; cmux vm terminal output <id> "$t" > "$t.log"; done267```268 269`--wait` polls the process (Ctrl-C stops your wait, not the agent), `--output` pages the full scrollback after exit, and the agent's exit code becomes yours (1 on a timeout or signal, with a line saying which).270 271Inside the machine the agent authenticates like it would locally (its own login, or CodeRouter's env/config under `/root`, set once with `vm exec`). Never copy the user's tokens onto a machine unless they ask.272 273## 2b. Agents talking to agents (same machine, and across machines)274 275On one machine, an agent drives a sibling terminal headlessly — from the Mac or from inside the machine with the same verbs:276 277```bash278# from the Mac279cmux vm terminal send <id> <term> 'run the failing test again' --keys enter280cmux vm terminal wait <id> <term> --pattern '❯|\$ $' --timeout 600 && cmux vm terminal read <id> <term>281# from inside the machine (an agent's own hooks/scripts); default target = its own terminal282cmux send-key --terminal <term> enter283cmux terminal read <term>284```285 286Across machines, an existing peer route lets the source machine speak to the peer with the Mac grammar. This build cannot create new peer grants:287 288```bash289# inside <builder>:290cmux vm agent reviewer --agent codex --name "review" --cwd work/app -- "review the diff on branch feat/x and write REVIEW.md"291cmux vm terminal wait-exit reviewer <term> --timeout 1800                     # the agent's process ended292cmux vm terminal output reviewer <term> | tail -n 40                          # what it said293cmux vm exec reviewer -- cat work/app/REVIEW.md294cmux vm env set reviewer GITHUB_REPO=org/app                       # settings for the peer's shells295cmux vm push reviewer ./deploy_key ~/.ssh/deploy_key --mode 600    # one file over the link into the peer's `cmux file receive`; never through exec296cmux vm agent reviewer --agent codex --wait --output -- "summarize REVIEW.md in three lines"   # until-done on the peer297cmux vm layout apply reviewer review-layout.json --name review     # a workspace on the peer, ready for the human298```299 300A machine never holds a control-plane credential and can reach only its previously configured peers. The earlier Mac enrollment broker is no longer implemented.301 302## 3. Repo with history (private repos, no credentials on the machine)303 304```bash305git bundle create /tmp/repo.bundle --all306cmux vm push <id> /tmp/repo.bundle work/repo.bundle307cmux vm exec <id> -- sh -c 'cd work && git clone repo.bundle app && cd app && git checkout main'308```309 310Public repos can just clone on the machine: `cmux vm exec <id> -- git clone https://github.com/org/repo work/repo`.311 312## 4. Builds and tests in the cloud instead of the local Mac313 314```bash315t=$(cmux surface new-terminal --machine <id> --no-open --json -- sh -c 'cd work/app && make test' | jq -r .terminal_id)316cmux vm terminal wait-exit <id> "$t" --timeout 900        # exited code=<n> | exited signal=<s> | pending (exit 1)317cmux vm terminal output <id> "$t" > test.log              # everything the run printed, not just the visible screen318cmux vm pull <id> work/app/dist ./dist-from-cloud319```320 321A durable terminal outlives the CLI call and the Mac; `wait-exit` returns the exit code and `output` the full log (`--json` gives `next_offset`, so a long run can be read incrementally with `--after`). For a quick command that finishes in seconds, `cmux vm exec <id> --timeout 300 -- <cmd>` is enough. Report the real outcome from the exit code and the log — a finished wait is not a passed test.322 323## 5. Parallel experiments with checkpoints and forks324 325```bash326cmux vm snapshot <id> --name pre-experiment327fork_a=$(cmux vm fork <id> --name try-approach-a --detach --json | jq -r '.id')328fork_b=$(cmux vm fork <id> --name try-approach-b --detach --json | jq -r '.id')329cmux vm agent --agent codex --machine "$fork_a" --no-open -- exec "try approach A in work/app"330cmux vm agent --agent codex --machine "$fork_b" --no-open -- exec "try approach B in work/app"331cmux vm tree                                           # both agents, side by side332cmux vm rm "$fork_a"; cmux vm rm "$fork_b"             # only the forks you created333```334 335## 6. Desktop and browser tasks336 337Desktop machines run xfce + TigerVNC + noVNC and the CUA driver (`cua-computer-server`, the computer-use API that screenshots/clicks/types on display `:1`). Drive it from inside the machine (`vm agent` with a computer-use-capable agent, or your own script against the server), and show the human the screen:338 339```bash340cmux vm open <id>:desktop              # the screen as a browser pane beside the shell341cmux vm exec <id> -- sh -c 'DISPLAY=:1 xdotool key ctrl+l'   # quick desktop pokes342```343 344## 7. Showing the human345 346```bash347cmux vm tree <id>                      # the map: which terminal is which, what is already open348cmux vm open <id>/<ws>/<term>          # one terminal as a pane (reuses an open pane)349cmux vm open <id>                      # shell (+ screen on desktop machines)350cmux vm open <id>:desktop              # the screen351cmux vm open <id>:port/3000            # the app they should look at352cmux vm handoff <id>                   # attach block another human/agent can follow353```354 355Pair with `cmux notify` so they know why a pane appeared. Prefer `--print`/`--detach`/`--no-open` until the moment you intend the user to look; `vm open` never steals focus unless `--focus true`.356 357## 8. Cleanup etiquette358 359- New cmux machines have no idle timeout and remain available until explicitly paused or360  stopped. Older/provider-managed machines may still be asleep; opening or running a command361  wakes them, so leaving one for the user to inspect is fine (say so in your handoff).362- Delete forks and scratch machines you created once their purpose is served.363- Never `vm rm` or `vm base reset` a machine you didn't create without explicit user confirmation — both discard data permanently.364