Resources

# cmux Cloud skill

You are helping the user work with cmux Cloud machines through the `cmux` CLI. This file is regenerated by the cmux app; do not edit it. `cmux vm <subcommand> --help` is authoritative when this file disagrees.

## Mental model

- A machine is a persistent cloud VM owned by the signed-in cmux user. Its generated name (like `brave-otter`) is its address everywhere; `cmux vm rename` sets a display label only. The machine outlives panes, closed laptops, and reconnects.
- Every machine runs a cmux session daemon (cmux-tui on current images, cmuxd-remote on older ones) that owns terminal sessions and scrollback. Clients attach through short-lived leases minted by the backend; the transport depends on what the provider and image support. SSH is a fallback some providers and images cannot mint, and its absence is not an error.
- New machines boot a desktop image (xfce + noVNC) plus a shell, with a persistent per-machine home. `--base` gives a shell-only machine.
- Base is a separate single per-user persistent slot, pinned to the top of the sidebar. `cmux vm new` mints fresh machines; `cmux vm base` always reopens the same one.
- Terminals on a machine live in its cmux-tui session (workspaces `ws_…`, terminals `term_…`). They keep running detached. `cmux vm tree` catalogs every surface, and every line is an address `cmux vm open` (machine targets) or `cmux surface open` (any entry, including This Mac) accepts: `brave-otter/main/term_2f9c…`, `brave-otter:desktop`, `brave-otter:port/3000`.
- Pool machines (labeled `agent-pool` in `cmux vm ls`) are provisioned by the `vm run`/`vm agent` router and reused for routed work. The router never drafts machines a person made by hand.
- Plans cap active machine count and memory. `cmux vm ls` prints the meter and, on free plans, when free cloud access expires.

## Commands

List and inspect:

```
cmux vm ls                    # NAME LABEL STATE PROVIDER IMAGE + plan meter
cmux vm status <id>           # provider, status, image
cmux vm stats <id>            # live CPU/memory
cmux vm ports <id>            # listening TCP ports inside the machine
cmux vm tools <id>            # probe common tools inside the machine
cmux vm tree [<machine>|local] [--refresh]
```

Create and name:

```
cmux vm new [--base] [--size <2g|4g|8g|16g|32g>] [--detach|-d]
cmux vm rename <id> <new-label>      # label only; the id stays the address
```

`vm new` takes no positional arguments (rejected so a typo cannot provision a paid machine). A bare `vm new` creates a persistent machine with its own durable home, up to the plan limit. The backend picks the provider.

Base:

```
cmux vm base                  # open Base, reuses the same VM
cmux vm base reset [--reason <text>]   # new generation; the old VM is retained
```

Attach and open:

```
cmux vm shell <id>                       # terminal workspace (WebSocket attach)
cmux vm tui <id>                         # the machine's full cmux-tui client in a pane
cmux vm desktop <id>                     # noVNC screen as a browser pane
cmux vm open <machine>                   # same as vm shell
cmux vm open <machine>/<ws>[/<term>]     # a cmux-tui workspace or one terminal
cmux vm open <machine>:desktop
cmux vm open <machine> <port> [--print]  # private tokened URL for an HTTP port
cmux vm ssh <id>                         # SSH fallback; unavailable on some providers/images
```

Machine workspaces, terminals, and panes (everything the Cloud sidebar does):

```
cmux vm workspace new <id> [--name <n>]     # create a workspace on the machine (its ⌘N) and open it here
cmux vm workspace open <id> <ws> [--here|--tabs|--pane <p> --left|--right|--up|--down]
cmux vm workspace rename <id> <ws> <name>
cmux vm workspace rm <id> <ws>              # close the workspace AND kill every terminal in it (the sidebar's Close Workspace…)
cmux vm workspace close <id> <ws>           # CLI-only: close the workspace but keep its terminals running in the Terminals pool
cmux vm terminal close <id> <term>          # end one terminal (the process and its tab)
cmux vm terminal send <id> <term> 'bun test' --keys enter   # type into a terminal headlessly, then press keys (no pane, no focus)
cmux vm terminal wait <id> <term> --pattern 'pass|fail' [--timeout 120]   # block until the screen matches; exit 1 on timeout
cmux vm terminal read <id> <term>           # the terminal's visible screen (what a person would see)
cmux surface ls [--json]                    # every surface (This Mac + machines) and which panes show it
cmux surface open <machine>/<kind>/<key> [--new] [--pane <p> --left|--right|--up|--down|--tab]
cmux surface new-terminal --machine <id> [--remote-workspace <ws>] [--cwd <dir>] [-- <cmd...>]
```

A pane showing a machine surface is an ordinary local cmux pane: move, split, reorder, or close it with the local workspace/pane commands (`cmux --help`), and closing a pane never kills the machine's terminal. Workspace (`ws_…`) and terminal (`term_…`) ids come from `cmux vm tree`.

`terminal send/wait/read` is how you drive an interactive program on a machine (a REPL, a TUI, a long test run, another agent's session) without attaching a pane or taking the user's focus: start it with `surface new-terminal --machine <id> --no-open -- <cmd>`, then send input, wait for the prompt or result pattern, and read the screen. Open a pane for the person only when there is something to show.

Run commands:

```
cmux vm exec <id> -- <command...>        # one command, ~35s limit, exit code passes through
cmux vm run [--sync] [--pull <remote-path>] [--machine <id>] [--new] [--size <s>] [--timeout <seconds>] -- <command...>
cmux vm route [--cwd <dir>]              # print which machine vm run/agent would pick, and why
cmux vm wait <id> [--timeout <seconds>] [--wake]
```

`vm run` needs no machine name: it reuses an idle pool machine, wakes a sleeping one, or provisions a fresh one (default timeout 600s, max 15 minutes). `--sync` pushes the current directory to `work