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
```

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/<basename>` first; `--pull` fetches a path back afterward. For longer work start a detached terminal via `vm agent`.

Coding agents on machines:

```
cmux vm agent --agent <claude|codex|opencode|pi> [--machine <id>] [--sync] [--cwd <dir>] [--name <name>] [--no-open] [--new] [--size <s>] -- <prompt or args...>
```

The agent starts as a detached terminal in the machine's cmux-tui session: it keeps running when the pane closes, and `cmux vm open <machine>/<ws>/<term>` reattaches from any device. A bare prompt runs the agent's one-shot form; leading flags or known subcommands pass through verbatim. Credentials for cloud agents come from `cmux ai-accounts upload`.

Files:

```
cmux vm push <id> <local-path> [remote-path] [--exclude <pattern>]...
cmux vm pull <id> <remote-path> [local-path]
```

Directories travel as tarballs with default excludes (node_modules, .git, and similar); transfers are size-capped, so ship repos without build artifacts.

Snapshot, fork, restore:

```
cmux vm snapshot <id> [--name <name>]
cmux vm fork <id> [--name <name>]
cmux vm restore <snapshot-id>
```

Destroy:

```
cmux vm rm <id>          # irreversible and unprompted
```

## Inside a machine

The guest `cmux` binary is the machine's relay CLI: commands go to the connected cmux app on the user's Mac; they do not act inside the VM. The most useful verb for agents running on a machine:

```
cmux notify --title "Build done" --subtitle "myrepo" --body "Tests green"
```

## Rules

- Never run `cmux vm rm` on a machine you did not create in this session unless the user names it this turn. Use `cmux vm base reset` for a fresh Base; it retains the old VM.
- Prefer `vm run`/`vm agent` routing over creating machines; creation bills the user and counts against the plan. Check `cmux vm ls` before `vm new`.
- Use `cmux vm wait` instead of polling `vm status`.
- Use `--json` only on commands whose `--help` documents it; interactive verbs (`shell`, `tui`, `desktop`) have none. Do not parse the human table output either way.
- `vm exec` quoting is faithful per argv element; wrap shell constructs as `-- sh -c '<script>'`.
- Read plan limits and sizes from `cmux vm ls` and `--help`, not from memory.