cmux-cloud

cmux Cloud

通过 cmux CLI 操控 cmux Cloud 机器（用户拥有的持久化 Linux VM）：创建并连接、运行命令和编码 Agent、传输文件、开放端口和桌面、创建快照／分叉／恢复，并从机器内部发送通知。每条命令的完整语法见 references/commands.md；如果内容不一致，请以已安装版本中的 cmux vm <sub> --help 为准。

心智模型

• 机器是已登录 cmux 用户拥有的持久化云 VM。其生成的名称（brave-otter）是它在所有地方的地址；cmux vm rename 只会设置显示标签。云后端会选择提供商；机器的生命周期独立于你的窗格、Mac 关闭以及重新连接。
• 每台机器都运行一个 cmux 会话守护进程（当前镜像为 cmux-tui，旧版镜像为 cmuxd-remote），负责管理终端会话和滚动缓冲区。客户端（Mac 窗格、iOS）通过后端签发的短期租约进行连接；具体传输方式取决于提供商和镜像支持的功能。SSH 是一种回退方式，某些提供商和镜像完全无法签发 SSH；缺少 SSH 并非错误。
• 新机器会启动一个 桌面镜像（xfce + noVNC）和 shell，并拥有持久化的机器专属主目录。--base 会创建仅包含 shell 的机器。
• Base 是单独的、每位用户一个的持久化槽位，固定显示在侧边栏顶部。vm new 会创建全新的机器；vm base 总是重新打开同一台机器。
• 机器上的终端位于其 cmux-tui 会话中（工作区 ws_…，终端 term_…）。它们会在分离状态下继续运行；cmux vm tree 会列出每个界面（本地和云端），其中每一行都是 cmux vm open（机器目标）或 cmux surface open（包括 This Mac 在内的任意条目）可接受的地址，例如 brave-otter/main/term_2f9c…、brave-otter:desktop、brave-otter:port/3000。
• 池机器（在 vm ls 中标记为 agent-pool）由 vm run／vm agent 路由器配置并复用于路由的工作。路由器绝不会草拟用户手动创建的机器。
• 计划会限制活跃机器数量和内存。cmux vm ls 会显示用量计量（N of M machines on the <plan> plan），并在免费计划下显示免费云访问的到期时间。

前置条件

主机端命令通过正在运行的 cmux macOS 应用的套接字执行：应用必须正在运行且已登录（机器归该账户／团队所有）。cmux --version、cmux ping，然后执行 cmux vm ls，是最快的健康检查。文档中注明支持 --json 的命令均支持脚本调用。创建机器需要付费并计入计划用量；尽量复用而非创建新机器。

工作流

运行一次性命令

cmux vm run -- uname -a                       # router picks/wakes/creates a pool machine
cmux vm run --sync -- bun test                # push current dir to work/<basename> first
cmux vm run --sync --pull work/app/dist -- sh -c 'cd work/app && bun run build'
cmux vm exec <id> -- pwd                      # when you already know the machine

exec 会在客户端运行约 35 秒后放弃；vm run 最多允许运行 15 分钟。对于耗时更长的任务，请启动分离终端（vm agent 或 cmux surface new-terminal --machine <id> -- <command...>），然后通过 vm tree／vm open 查看运行情况。

在云端运行编码 Agent

cmux vm agent --agent claude --sync -- "run the test suite and fix failures"
cmux vm agent --agent codex --machine brave-otter -- exec "summarize work/app"

Agent（预装了 claude、codex、opencode、pi）会以分离终端的形式在机器的 cmux-tui 会话中启动：关闭窗格不会终止它们；通过 cmux vm open <machine>/<ws>/<term> 可从任何设备重新连接。云端 Agent 的凭据来自 cmux ai-accounts upload。

创建、连接、检查

cmux vm new --detach                # fresh persistent machine; prints id + next commands
cmux vm shell <id>                  # terminal workspace on it (managed attach)
cmux vm desktop <id>                # its noVNC screen as a browser pane
cmux vm tui <id>                    # the machine's full cmux-tui client in a pane
cmux vm base                        # the persistent Base slot
cmux vm status <id>; cmux vm stats <id>; cmux vm ports <id>; cmux vm tools <id>

预览机器上运行的服务器

cmux vm open <id> 3000              # private tokened URL, opened as a browser pane
cmux vm open <id> 3000 --print      # just print the URL

传输文件

cmux vm push <id> ./myrepo work/myrepo      # dirs travel as tarballs, node_modules/.git excluded
cmux vm pull <id> work/report.pdf

保存并复现状态

cmux vm snapshot <id> --name before-upgrade
cmux vm restore <snapshot-id>               # new machine from the snapshot
cmux vm fork <id>                           # copy of a running machine

机器内部

访客机中的 cmux 二进制文件是机器的中继 CLI。它的命令会转发到用户 Mac 上已连接的 cmux 应用，而不是在虚拟机中执行：cmux notify 会向用户的通知中心发送通知，cmux browser … 会操作 Mac 的浏览器窗格，cmux read-screen / send / 工作区和窗格相关动词会操作 Mac 的 UI。它会依次从 CMUX_SOCKET_PATH、~/.cmux/socket_addr 和云端 CLI 桥接套接字解析其套接字；如果没有客户端连接，中继命令就会失败——这是预期行为，并不意味着安装有问题。

每个云端 Agent 都应该了解的命令：

cmux notify --title "Build done" --subtitle "myrepo" --body "Tests green, artifact in work/dist"

--workspace/--surface 默认读取 CMUX_WORKSPACE_ID/CMUX_SURFACE_ID，因此通知会归属于发出调用的窗格。Agent 工具路径位于 /root/.npm-global/bin、/root/.bun/bin、/root/.local/bin；如果工具“找不到”，请使用登录 Shell（bash -lc）。

规则

• 除非用户在本轮明确指定，否则绝不能对本会话中并非由你创建的机器运行 cmux vm rm。该操作不可逆，且未经请求。用户需要一个全新的 Base 时，请使用 cmux vm base reset，这样会保留旧虚拟机。
• 绝不能向 cmux vm new 传入名称——该命令不接受位置参数（为防止意外付费创建，传入参数会被拒绝）。请先创建，再运行 cmux vm rename。
• 优先使用 vm run/vm agent 路由，而不是创建机器；创建机器会计入方案限额并向用户收费。运行 vm new 前，请先检查 cmux vm ls。
• 不要循环运行 vm status 等待就绪；请使用 cmux vm wait <id> [--wake]。
• 除非托管连接路径失败，否则不要使用 cmux vm ssh；某些提供商和映像无法创建 SSH，因此应将“SSH unavailable”视为正常情况，而不是需要修复的错误。如果回退，请在交接说明中解释原因。
• 不要调用内部连接辅助命令（vm ssh-attach、vm-pty-attach、vm-ssh-attach、vm-pty-connect、vm-tui-connect、vm-tui-approve）。
• vm exec 会忠实保留每个 argv 元素的引号；不要预先加引号。请将 Shell 结构包装为 -- sh -c '<script>'。
• 提供商的选择由后端决定。只有在用户要求回滚或进行实验时才使用 --provider。
• 仅在 --help 中说明支持 --json 的命令上使用它；交互式动词（shell、tui、desktop）不支持该选项。无论如何，都不要解析人类可读的表格输出。
• 方案限额、规格和提供商可能会变化；请从 cmux vm ls 和 --help 的输出中读取，不要假设本文件中的值仍然适用。