Cloud Workspaces and Agents

A Cloud workspace works like a local cmux workspace, but its terminals run on a cloud machine. This page covers durable terminals, running agents, notifications, and the tools that are installed on every machine.

Durable terminals

Terminals live in the machine's daemon, not in your Mac. They keep running when you close a pane, quit cmux, lose Wi-Fi, or close your laptop. Open the machine again from any signed-in Mac and the terminal still has its output and its running process.

If the connection drops, the pane shows Cloud session disconnected with a Reconnect button, and cmux retries on its own.

If the machine's daemon restarts, cmux restores the workspace layout, but processes that were running do not survive the restart.

Closing a workspace keeps its terminals running as detached. Removing a workspace stops its terminals.

Run coding agents

Claude Code, Codex, OpenCode, and Pi are installed on every machine. Open a Cloud workspace and start the agent as you do locally. Agent hooks are already set up, so agent status and notifications reach your Mac.

cmux vm agent starts an agent on a machine from your Mac. With a prompt, it uses the agent's one-shot mode. Add --sync to upload the current directory first and --wait to wait for the result.

cmux vm agent --agent claude --machine brave-otter -- "add tests for the parser"
cmux vm agent --agent codex --machine brave-otter --sync --wait -- "fix the build"
cmux vm agent --agent opencode --new --size 16g -- "profile the importer"

cmux vm prompt installs a cmux Cloud skill for your local agent and prints a prompt that teaches it to use Cloud machines.

cmux vm prompt --open claude

Run commands

cmux vm run runs a command on a machine and returns its exit code. The first run from a directory picks a machine and remembers it for that directory for 14 days. Add --sync to upload the directory first and --pull to download a result.

cmux vm run -- npm test
cmux vm run --sync --pull dist -- npm run build
cmux vm route --json

cmux vm exec runs a short command without a terminal. It is for quick checks. Its timeout is 30 seconds by default and 5 minutes at most. Use cmux vm run, cmux vm agent, or a workspace terminal for long work.

cmux vm exec brave-otter -- uname -a
cmux vm exec --timeout 120 brave-otter -- docker ps

Start a dev server

cmux vm dev uploads a project, finds how to start it, and opens it in a workspace with the server and a browser. It detects package.json projects, Cargo, Go, Makefile dev targets, Django, uv, pyproject, requirements.txt, and static index.html sites. Use --dry-run to see the plan first.

cmux vm dev brave-otter --dry-run
cmux vm dev brave-otter . --port 3000

Notifications

cmux notify inside a machine shows a notification on your Mac for that terminal. Agent hooks send notifications when an agent finishes, needs approval, asks a question, or fails. Titles are limited to 128 bytes and bodies to 1 KB, and bursts are rate limited.

# Inside a Cloud machine
cmux notify --title "Build" --body "Tests passed"

Paste images

Press ⌘V with an image on the clipboard in a Cloud terminal. cmux uploads the image to the machine and pastes the remote path, so Claude Code and Codex can read it. PNG, JPEG, GIF, and WebP are supported, up to 20 MB each and 8 images at a time.

Layouts and terminals from the CLI

cmux vm workspace creates, opens, renames, closes, and removes workspaces on a machine. cmux vm terminal sends text, reads output, and waits for text or for exit. cmux vm tree shows the machine's workspaces and terminals. cmux vm layout export and apply use the same JSON as cmux new-workspace --layout.

cmux vm tree brave-otter
cmux vm workspace new brave-otter --name review
cmux vm terminal send brave-otter term_2f9c "npm run dev" --keys enter
cmux vm terminal wait brave-otter term_2f9c --pattern "ready" --timeout 60
cmux vm terminal read brave-otter term_2f9c
cmux vm layout export brave-otter review > layout.json
cmux vm layout apply brave-otter layout.json --open

What is installed

Machines run Ubuntu 24.04. You work as the user cmux with passwordless sudo, not as root. Docker starts at boot.

• Languages and tools: Node.js LTS, Bun, Python 3.12, uv, Docker, git, the GitHub CLI, ripgrep, fd, fzf, jq, tmux, sqlite3, build tools, vim, nano, and rsync.
• Browser and desktop: Chrome, agent-browser, a VNC desktop, and Ghostty.
• Agents: Claude Code, Codex, OpenCode, and Pi. They are pinned to tested versions and update when the machine image updates.

If an agent command is not found right after you create a machine, setup is still running. The setup log is at /tmp/cmux/provision.log.

Model access

Agents on a machine can use cmux's model routing without a key on the machine. The real credential is added outside the machine, so no account token is stored in the VM. You can also sign in to an agent inside the machine, or upload accounts for your team with cmux ai-accounts upload.

cmux ai-accounts list
cmux ai-accounts upload claude
cmux coderouter status

CodeRouter docs: supported accounts, sharing, and usage

The cmux CLI inside a machine

Inside a machine, the cmux command controls that machine's session. It supports tree, new-workspace, new-split, send, send-key, read-screen, terminal, layout, env, notify, open-url, and self. cmux self shows the owner, the machine, and your other machines. cmux vm verb peer controls your other machines from inside a machine.

# Inside a Cloud machine
cmux tree
cmux new-split right
cmux self peers
cmux vm exec calm-heron -- git status

Sign-in, AI account upload, and machine lifecycle commands such as new, delete, checkpoint, fork, resize, pause, domains, open, and vpn run only on your Mac.

iPhone

The cmux iOS app does not manage Cloud machines. A machine that is starting shows as a placeholder card.