cmux Cloud

Drive cmux Cloud machines (user-owned persistent Linux VMs) through the cmux CLI: create and attach, run commands and coding agents, move files, open ports and desktops, snapshot/fork/restore, and send notifications from inside a machine. Full per-command syntax lives in references/commands.md; cmux vm <sub> --help on the installed build is authoritative when they disagree.

Mental model

• A machine is a persistent cloud VM owned by the signed-in cmux user. Its generated name (brave-otter) is its address everywhere; cmux vm rename sets a display label only. The cloud backend picks the provider; the machine outlives your panes, your Mac being closed, 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 (Mac panes, iOS) 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 at all, 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. vm new mints fresh machines; 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 (local and cloud) and every line is an address cmux vm open (machine targets) or cmux surface open (any entry, including This Mac) accepts, e.g. brave-otter/main/term_2f9c…, brave-otter:desktop, brave-otter:port/3000.
• Pool machines (labeled agent-pool in 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 (N of M machines on the <plan> plan) and, on free plans, when free cloud access expires.

Prerequisites

Host-side commands go through the running cmux macOS app's socket: the app must be running and signed in (machines belong to that account/team). cmux --version, cmux ping, then cmux vm ls is the fastest health check. Commands that document --json support it for scripting. Creating machines costs money and counts against the plan; prefer reuse over creation.

Workflows