cmux-freestyle

cmux Freestyle

ユーザーが、cmux バックエンドから Cloud VM を起動できる Freestyle VM スナップショットを必要としている場合に、このスキルを使用します。専用の公開リポジトリである manaflow-ai/cmux-freestyle に置かれているため、Freestyle API キーを持つ人なら誰でも、シェルスクリプトを 1 つ実行するだけで FREESTYLE_SANDBOX_SNAPSHOT ID を取得できます。

Freestyle スナップショットは、作成したアカウントに紐付けられます。 manaflow のアカウントや他のユーザーのスナップショット ID は、別の Freestyle アカウントでは使用できません。すべてのユーザーが、自分の FREESTYLE_API_KEY を使ってセットアップスクリプトを実行する必要があります。近道はありません。

使用するタイミング

• ユーザーが、自分の cmux を Freestyle に接続する方法を尋ねている場合。
• ユーザーが cmux の Web バックエンドをセルフホストしており、特定の cmux リリースに固定されたスナップショットを必要としている場合。
• ユーザーが、自分の Freestyle アカウントで cmux Cloud VM イメージを再構築したい場合。
• ユーザーが、リポジトリ内のビルダー repo/web/scripts/build-cloud-vm-images.ts ではなく、スタンドアロンリポジトリ（cmux-freestyle）で作業したい場合。

新しいスナップショットを manaflow の Freestyle アカウントにプッシュし、repo/web/services/vms/images/manifest.json を更新する cmux の内部開発では、引き続き repo/web/scripts/build-cloud-vm-images.ts を使用してください。このスキルは外部ユーザー向けの手順です。

ビルド内容

リポジトリ内のビルダーにある freestyleBaseDockerfileContent を反映した Dockerfile から、Freestyle スナップショットを作成します。

• ubuntu:24.04、C.UTF-8、同じシェルパッケージ一式、および cmux ブラウザープロキシに必要な Python/OpenSSL シム。
• 固定された manaflow-ai/cmux GitHub リリースからダウンロードし、イメージのビルド中に cmuxd-remote-checksums.txt と照合して SHA-256 を検証した cmuxd-remote Linux/amd64。
• /usr/local/bin/cmux を cmuxd-remote へのシンボリックリンクとして設定。
• Node.js、Bun、およびバージョンを固定したコーディングエージェント CLI（Claude Code、OpenCode、Codex、Pi）。
• パスワードなしで sudo を実行できる Linux ユーザー cmux。
• Freestyle のポート 443 -> 7777 で cmuxd-remote serve --ws --listen 0.0.0.0:7777 --auth-lease-file ... --rpc-auth-lease-file ... を実行する Systemd ユニット cmuxd-ws.service。

イメージではリポジトリ内のビルダーと同じスモークテストを実行するため、失敗は稼働中の VM 内で後から発生するのではなく、スナップショットのビルド時に検出されます。

使用方法

リポジトリは自己完結型で、cmux のチェックアウトは不要です。

git clone https://github.com/manaflow-ai/cmux-freestyle.git
cd cmux-freestyle
export FREESTYLE_API_KEY=fk_...
./setup.sh

または、次のワンライナーを使用します。

FREESTYLE_API_KEY=fk_... \
  curl -fsSL https://raw.githubusercontent.com/manaflow-ai/cmux-freestyle/main/install.sh | bash

./setup.sh snapshot（デフォルトのサブコマンド）で使用できる便利なフラグ／環境変数：

• --release <tag> または CMUX_RELEASE_TAG=<tag> で cmuxd-remote のリリースを固定します。デフォルトは manaflow-ai/cmux の最新の安定版リリースです。
• --name <name> または CMUX_FREESTYLE_SNAPSHOT_NAME で Freestyle スナップショット名を設定します。
• --skip-cache または CMUX_FREESTYLE_SKIP_CACHE=1 で Freestyle のクリーンビルドを強制します。
• --codex-spec none、--claude-spec none などで、個別のエージェント CLI を除外します。
• --json で機械可読な結果を出力します。通常の方法では最後に FREESTYLE_SANDBOX_SNAPSHOT=sh-... が出力されます。

ビルドには、Freestyle のレイヤーキャッシュによって 5～15 分かかります。

セルフホスト用フルバンドル

./setup.sh は 4 つのサブコマンドを持つディスパッチャーです。スナップショット ID だけでなく、さらに必要な場合はこれらを組み合わせて使用してください。

./setup.sh doctor                         # validate tools, env, Freestyle key, GitHub release
./setup.sh                                # mint a snapshot under the user's Freestyle account
./setup.sh web --snapshot sh-xxxxxx       # clone manaflow-ai/cmux, write web/.env.local, start Docker Postgres
./setup.sh home --ref feat-ink-rewrite    # install cmux-home (Ink TUI) headquarters view

web は Next.js の開発環境をセットアップします。manaflow-ai/cmux を ~/cmux-freestyle-cmux にクローンし、Freestyle と Cloud VM の環境変数を web/.env.local に書き込み、bun install を実行します。また、--no-postgres が指定されていない場合は、ワークツリーごとの Docker Postgres を起動します。Stack Auth のキー（STACK_SECRET_SERVER_KEY、NEXT_PUBLIC_STACK_PROJECT_ID、NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY）は、エクスポートされていれば使用されますが、必須ではありません。このスクリプトに必要なのは git と bun です（Postgres を使用する場合は docker も必要です）。 home は「本部ビュー」です。Ink/TypeScript 版の cmux-home を ~/cmux-freestyle-home/ink にインストールして準備します。TUI はローカルの cmux アプリの Unix ソケットに接続し、すべてのワークスペースと Codex/Claude コンポーザーを、エンドユーザー向けの Node 専用ダッシュボードとして提供します。Ink 版は現在 feat-ink-rewrite ブランチにあります。main にマージされたら、デフォルトの --ref を切り替えてください。cmux-home リポジトリのルートにある Rust クレートは、引き続きフル機能の上流版です。

bun dev の実行時に環境変数 FREESTYLE_API_KEY が設定されている場合（home スクリプトは、ユーザーの ~/.secrets/cmux.env とシェルから値をエクスポートします）、cmux-home はワークスペース一覧の下に Freestyle VMs (N) というタイトルの第 2 パネルを表示します。各行には VM ID、状態、スナップショット ID（./setup.sh snapshot のもの）、経過時間が表示されます。これにより、TUI はローカルの cmux ワークスペースとユーザーの Freestyle Cloud VM の両方を表示する単一のダッシュボードとなり、選択カーソルは両方のパネルを行き来します。

VM を選択すると、その行で次の操作が有効になります。

• enter はサンドボックスのワークフローを開始します。freestyle-vm-ssh <vmId> を実行する新しい cmux ワークスペースを作成します。ヘルパースクリプトは短時間有効な Freestyle SSH ID を発行し、vm-ssh.freestyle.sh 経由で SSH セッションを開きます。このセッションには、ローカルの Subrouter AI ゲートウェイ（127.0.0.1:31415）へのリバースフォワード -R 31415:127.0.0.1:31415 と、一般的な開発ポート（3000、5173、8000、8080）への -L フォワードが含まれます。VM 内に、openai_base_url がフォワードされた Subrouter を参照する ~/.codex/config.toml を書き込み、その後ログインシェルを起動します。そのシェル内で起動した Codex は、ユーザーの Mac 上の Subrouter 経由でルーティングされます。右側には http://127.0.0.1:3000 を開いたブラウザペインも表示されます。
• ctrl+o はローカル Codexのワークフローを開始します。TUI の --cwd を使う通常の cmux ワークスペースを作成します。SSH は使用せず、右側には https://<vmId>.vm.freestyle.sh を開いたブラウザペインを表示します。Codex/Claude はローカルのチェックアウトに対して Mac 上で実行され、VM はリモート開発サーバーとして扱われます。
• ctrl+x は Freestyle SDK を通じて VM を破棄します。
• Freestyle VMs (N) ヘッダー上で ctrl+n を押すと、FREESTYLE_SANDBOX_SNAPSHOT から新しい VM を作成します。

Freestyle ゲートウェイの制約。 vm-ssh.freestyle.sh の Freestyle SSH ゲートウェイは -R によるリモートポートフォワーディングを拒否します（remote port forwarding failed for listen port 31415）。そのため、--reverse-subrouter フラグはオプトインであり、通常の Linux/macOS の sshd ホストでのみ動作します。

Freestyle VM 内の Codex のデフォルトパス（現在動作します）：freestyle-vm-ssh は tsadmin api POST /tailnet/-/keys を通じて、一時的な事前認証済み Tailscale キーを発行します（タグは tag:server、有効期限は 1 時間）。ユーザー空間ネットワーク（--tun=userspace-networking）で VM 内の tailscale up を実行し、tailscaled の HTTP プロキシと SOCKS5 サーバーを 127.0.0.1:1055 で有効化します。さらに、すべてのログインシェルで HTTP_PROXY/HTTPS_PROXY/NO_PROXY がエクスポートされるよう /etc/profile.d/cmux-tailnet-proxy.sh を書き込み、openai_base_url = "http://subrouter-team.tail41290.ts.net:31415/v1" を含む ~/.codex/config.toml を書き込みます。これにより VM 内の Codex は、ローカルプロキシ経由で tailnet 上の既存の subrouter-team ホストに接続し、OpenAI へのすべてのトラフィックが Subrouter のアカウントスケジューリングを通じてルーティングされます。cmux-freestyle スナップショットには apt の tailscale パッケージがすでに含まれているため、初回の起動はエンドツーエンドで約 6 秒です。以降のセッションでは既存の状態を再利用します。

--no-tailscale を指定すると呼び出しごとに無効化できます。Subrouter の URL は --subrouter-url <url> または SUBROUTER_REMOTE_URL で、認証キーは --tailscale-authkey <key> または TAILSCALE_AUTHKEY で上書きできます。現在、Subrouter がルーティングするのは Codex のみです。Subrouter が Claude/OpenCode に対応するまでは、VM 内で Codex を使用してください。

ヘルパーには Mac 上の sshpass（brew install hudochenkov/sshpass/sshpass）と、PATH 上の tsadmin（skills/tsadmin/scripts/tsadmin）が必要です。

GitHub 認証

スナップショットビルダーが使用するのは、公開されている GitHub エンドポイント（/repos/manaflow-ai/cmux/releases/latest と、リリースアセットの cmuxd-remote-checksums.txt）だけです。未認証の GitHub API では、1 時間あたり 60 件のリクエストが許可されており、通常の利用には十分です。共有 IP、CI のループ、繰り返しの再ビルドなどでユーザーが 403／429 に遭遇した場合は、GITHUB_TOKEN（または GH_TOKEN）を設定してください。スクリプトは API 呼び出しとチェックサムのダウンロードの両方にトークンを渡します。CI 連携を案内する際は、この点についても伝えてください。

Freestyle SDK に必要なのは FREESTYLE_API_KEY だけです。スナップショットの作成に GitHub の認証情報は必要ありません。setup.sh web は manaflow-ai/cmux を匿名でクローンするため、こちらも認証は不要です。ユーザーが自分のフォークに対して git push したいと明示した場合に限り、gh auth login を案内してください。

スナップショットを cmux に接続する

スクリプトがスナップショット ID を出力したら、cmux バックエンド用の環境変数ブロックをユーザーに渡してください。

FREESTYLE_API_KEY=fk_...
FREESTYLE_SANDBOX_SNAPSHOT=sh-xxxxxxxxxxxxxxxxxxxx
CMUX_VM_DEFAULT_PROVIDER=freestyle
CMUX_VM_FREESTYLE_ENABLED=1

FREESTYLE_API_KEY と FREESTYLE_SANDBOX_SNAPSHOT は、同じ Freestyle アカウントのものを使用する必要があります。別のアカウントのスナップショット ID では起動に失敗します。

単発のスモークテストを行う場合：

npx -y freestyle vm create --snapshot <snapshotId> --ssh

VM 内で、すべてが正しく組み込まれていることを確認します。

cmuxd-remote version
cmux --help
claude --version
codex --version
node --version
bun --version

リポジトリでの反復作業

ビルダー全体は、scripts/build-snapshot.ts にある 1 つの TypeScript ファイルです。更新する際は、信頼できる唯一の情報源である repo/web/scripts/build-cloud-vm-images.ts と常に同期させてください。

• ピン留めされたエージェント CLI のバージョン（CLOUD_AGENT_TOOLS）。
• デフォルトの Node メジャーバージョンと Bun バージョン。
• Dockerfile の本文（freestyleBaseDockerfileContent、pythonOpenSSLCommands、toolInstallCommands、rootSetupCommands、imageSmokeTestCommands）。
• スナップショット作成呼び出しの形式と復旧動作（waitForFreestyleSnapshotByName）。

cmux がこれらのいずれかを変更した場合は、cmux-freestyle 内の対応する定数を更新し、リリースを公開してください。また、URL／チェックサムの仕様に変更があれば、スクリプトのデフォルト設定が参照する cmux のリリースタグも更新してください。

Freestyle CLI（npx -y freestyle vm ...）では、VM の作成、一覧表示、SSH 接続、コマンド実行、削除に対応していますが、スナップショットの作成には対応していません。そのため、このスクリプトでは freestyle SDK を直接使用します。CLI のみを使うシェルスクリプトに置き換えようとしないでください。

ルール

• 共有スナップショット ID がユーザーにも使えると約束しないでください。使えません。ユーザーごとに、自分の Freestyle API キーを使って ./setup.sh を 1 回実行する必要があります。
• プロバイダーの API キー、R2 の認証情報、その他ユーザー固有の情報をスナップショットに組み込まないでください。Dockerfile は公開情報のみから再現できる状態を保つ必要があります。
• スナップショットで未リリースの cmuxd-remote を指定しないでください。SHA-256 検証で基準として参照できるよう、公開済みの manaflow-ai/cmux リリースタグを使用してください。
• エージェント CLI のバージョンポリシーを緩和しないでください。仕様には正確な semver のバージョンを指定する必要があります。範囲指定と latest は、各再ビルドの再現性を確保するため、意図的に拒否されています。
• 反復作業の際に、manaflow の Freestyle アカウントを使用しないでください。個人の Freestyle アカウントを使用してください。manaflow のスナップショットのライフサイクルは、リポジトリ内のビルダーと cmux のイメージマニフェストによって管理されています。