cmux-cloud

cmux Cloud

cmux CLI を使って cmux Cloud マシン（ユーザー所有の永続的な Linux VM）を操作します。マシンの作成と接続、コマンドやコーディングエージェントの実行、ファイルの移動、ポートやデスクトップの公開、スナップショットの作成・フォーク・復元、マシン内からの通知送信ができます。各コマンドの詳細な構文は references/commands.md に記載されています。内容に食い違いがある場合は、インストール済みビルドでの cmux vm <sub> --help を正としてください。

基本的な考え方

• マシンは、サインイン中の cmux ユーザーが所有する永続的なクラウド VM です。自動生成された名前（brave-otter）があらゆる場所でのアドレスになります。cmux vm rename で変更できるのは表示名だけです。クラウドバックエンドがプロバイダーを選択します。マシンはペインや Mac の終了後も存続し、再接続できます。
• すべてのマシンでは、ターミナルセッションとスクロールバックを管理する cmux セッションデーモン（現行イメージでは cmux-tui、旧イメージでは cmuxd-remote）が動作します。クライアント（Mac のペイン、iOS）は、バックエンドが発行する短期間有効なリースを通じて接続します。トランスポートは、プロバイダーとイメージがサポートする方式によって異なります。SSH は一部のプロバイダーやイメージでは発行できないフォールバック手段であり、利用できなくてもエラーではありません。
• 新しいマシンは、シェルと永続的なマシンごとのホームディレクトリを備えた デスクトップイメージ（xfce + noVNC）で起動します。--base を指定すると、シェルのみのマシンになります。
• Base はユーザーごとに 1 つだけある別枠の永続スロットで、サイドバーの最上部に固定されます。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 対応と記載されたコマンドでは、スクリプト向けに --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 で状況を確認してください。

クラウドでコーディングエージェントを実行する

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"

エージェント（claude、codex、opencode、pi はプリインストール済み）は、マシンの cmux-tui セッション内で切り離されたターミナルとして起動します。ペインを閉じてもエージェントは終了せず、cmux vm open <machine>/<ws>/<term> を使えば、どのデバイスからでも再接続できます。クラウドエージェントの認証情報は 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 です。そのコマンドは VM 内で実行されるのではなく、ユーザーの Mac で接続中の cmux アプリに転送されます。cmux notify はユーザーの通知センターに通知を投稿し、cmux browser … は Mac のブラウザペインを操作し、cmux read-screen / send / ワークスペースおよびペイン関連の動詞は Mac の UI に作用します。ソケットは CMUX_SOCKET_PATH、次に ~/.cmux/socket_addr、最後にクラウド CLI ブリッジソケットの順に解決されます。クライアントが接続されていない場合、リレーコマンドは失敗します。これは想定どおりの動作であり、インストールの不具合ではありません。

すべてのクラウドエージェントが知っておくべきコマンド：

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

--workspace / --surface のデフォルト値には CMUX_WORKSPACE_ID / CMUX_SURFACE_ID が使われるため、通知は呼び出し元のペインに紐付けられます。エージェントのツールのパスは /root/.npm-global/bin、/root/.bun/bin、/root/.local/bin にあります。ツールが「見つからない」場合は、ログインシェル（bash -lc）を使用してください。

ルール

• このセッションで自分が作成していないマシンに対して、ユーザーがこのターンでその名前を指定しない限り、cmux vm rm を実行してはなりません。この操作は元に戻せず、明示的な依頼なしに実行してはなりません。ユーザーが新しい Base を求めている場合は、古い VM を保持する 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 の各要素に忠実に処理されます。事前に引用符を付けないでください。シェル構文は -- sh -c '<script>' の形式で囲んでください。
• プロバイダーの選択はバックエンドに任せてください。--provider は、ユーザーが依頼したロールバックまたは実験に限って使用してください。
• --json は、--help にその指定が記載されているコマンドでのみ使用してください。対話型の動詞（shell、tui、desktop）にはありません。いずれの場合も、人間向けのテーブル出力を解析してはなりません。
• プランの上限、サイズ、プロバイダーは変更されます。このファイルに記載された値を前提とせず、cmux vm ls と --help の出力から確認してください。