cmux-freestyle

cmux Freestyle

当用户需要一个 Freestyle VM 快照，供 cmux 后端启动 Cloud VM 时使用，请使用此技能。该项目位于独立的公开仓库 manaflow-ai/cmux-freestyle，任何拥有 Freestyle API 密钥的用户都可以运行一个 shell 脚本，并获取 FREESTYLE_SANDBOX_SNAPSHOT ID。

Freestyle 快照仅限创建它的账户使用。 manaflow 账户或其他用户创建的快照 ID，无法用于其他 Freestyle 账户。每位用户都必须使用自己的 FREESTYLE_API_KEY 运行设置脚本。没有捷径。

适用场景

• 用户询问如何让自己的 cmux 连接到 Freestyle。
• 用户自托管 cmux Web 后端，并需要绑定到已知 cmux 版本的快照。
• 用户想在自己的 Freestyle 账户上重新构建 cmux Cloud VM 镜像。
• 用户想迭代独立仓库（cmux-freestyle），而不是仓库内的构建脚本 repo/web/scripts/build-cloud-vm-images.ts。

对于 cmux 内部开发，如果需要将新快照推送到 manaflow 的 Freestyle 账户，并更新 repo/web/services/vms/images/manifest.json，请继续使用 repo/web/scripts/build-cloud-vm-images.ts。此技能适用于外部用户。

构建内容

使用 Dockerfile 构建 Freestyle 快照，该文件与仓库内构建器中的 freestyleBaseDockerfileContent 保持一致：

• ubuntu:24.04、C.UTF-8、相同的 shell 软件包集合，以及 cmux 浏览器代理所需的 Python/OpenSSL shim。
• 从固定版本的 manaflow-ai/cmux GitHub 发布版下载 Linux/amd64 版 cmuxd-remote，并在镜像构建期间使用 cmuxd-remote-checksums.txt 验证 SHA-256。
• 将 /usr/local/bin/cmux 符号链接到 cmuxd-remote。
• Node.js、Bun，以及固定版本的编码 Agent CLI（Claude Code、OpenCode、Codex、Pi）。
• 无需密码即可使用 sudo 的 Linux 用户 cmux。
• Systemd 单元 cmuxd-ws.service 在 Freestyle 端口 443 -> 7777 上运行 cmuxd-remote serve --ws --listen 0.0.0.0:7777 --auth-lease-file ... --rpc-auth-lease-file ...。

镜像会运行与仓库内构建器相同的冒烟测试，因此失败会在快照构建时显现，而不会等到运行中的 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 等用于移除相应的 Agent CLI。
• --json 输出机器可读结果；人类可读模式会在最后打印 FREESTYLE_SANDBOX_SNAPSHOT=sh-...。

构建需要 5 到 15 分钟，具体取决于 Freestyle 的层缓存情况。

完整自托管套件

./setup.sh 是一个包含四个子命令的分发脚本。用户需要的不只是快照 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，并启动每个工作树专用的 Docker Postgres（除非设置了 --no-postgres）。如果已导出 Stack Auth 密钥（STACK_SECRET_SERVER_KEY、NEXT_PUBLIC_STACK_PROJECT_ID、NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY），脚本会使用它们，但这些密钥并非必需。脚本只需要 git 和 bun（以及用于 Postgres 的 docker）。 home 是“总部视图”：它会在 ~/cmux-freestyle-home/ink 安装并准备 cmux-home 的 Ink/TypeScript 移植版。这个 TUI 会连接本地 cmux 应用的 Unix socket，为终端用户提供一个仅依赖 Node 的仪表盘，展示所有工作区，并提供 Codex/Claude 撰写器。Ink 移植版目前位于 feat-ink-rewrite 分支；合并到 main 后，请切换默认的 --ref。cmux-home 仓库根目录下的 Rust crate 仍是功能完整的上游版本。

如果运行 bun dev 时环境中设置了 FREESTYLE_API_KEY（home 脚本会从用户的 ~/.secrets/cmux.env 和 shell 中导出该变量），cmux-home 会在工作区列表下方渲染第二个面板，标题为 Freestyle VMs (N)。每行显示 VM ID、状态、快照 ID（即 ./setup.sh snapshot 使用的 ID）和运行时长。这样一来，这个 TUI 就成为同时展示本地 cmux 工作区和用户 Freestyle Cloud VM 的统一仪表盘，且同一个选择光标可在两个面板间移动。

选择 VM 后，可以对该行执行以下操作：

• enter 打开 sandbox 工作流：创建一个运行 freestyle-vm-ssh <vmId> 的新 cmux 工作区。辅助脚本会生成一个短时有效的 Freestyle SSH 身份，通过 vm-ssh.freestyle.sh 打开 SSH 会话，并使用 -R 31415:127.0.0.1:31415（反向转发到本地 127.0.0.1:31415 上的 Subrouter AI 网关），以及针对常见开发端口（3000、5173、8000、8080）的 -L 转发；接着在 VM 内写入 ~/.codex/config.toml，将 openai_base_url 指向转发后的 subrouter，然后进入登录 shell。在该 shell 中启动的 VM 内 Codex 会通过用户 Mac 上的 Subrouter 路由。还会在右侧打开一个浏览器窗格，地址为 http://127.0.0.1:3000。
• ctrl+o 打开 local-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 小时后过期），在 VM 内以用户空间网络模式运行 tailscale up（--tun=userspace-networking），在 127.0.0.1:1055 上启用 tailscaled 的 HTTP 代理和 SOCKS5 服务器，写入 /etc/profile.d/cmux-tailnet-proxy.sh，让每个登录 shell 都导出 HTTP_PROXY/HTTPS_PROXY/NO_PROXY，并写入 ~/.codex/config.toml，其中设置 openai_base_url = "http://subrouter-team.tail41290.ts.net:31415/v1"。随后，VM 内的 Codex 会通过本地代理，经由 tailnet 连接现有的 subrouter-team 主机，因此所有 OpenAI 流量都会通过 Subrouter 的账户调度进行路由。cmux-freestyle 快照已包含 apt tailscale 包，因此首次启动全程约需 6 秒；后续会话会复用现有状态。

可通过 --no-tailscale 在单次调用中禁用此功能；可通过 --subrouter-url <url> 或 SUBROUTER_REMOTE_URL 覆盖 subrouter URL；可通过 --tailscale-authkey <key> 或 TAILSCALE_AUTHKEY 覆盖 auth-key。目前 Subrouter 只路由 Codex，因此在 Subrouter 增加 Claude/OpenCode 支持之前，请在 VM 内使用 Codex。

辅助工具需要 Mac 上安装 sshpass（brew install hudochenkov/sshpass/sshpass），并且 tsadmin 位于 PATH 中（skills/tsadmin/scripts/tsadmin）。

GitHub 身份验证

快照构建器只会访问 GitHub 的公共端点（/repos/manaflow-ai/cmux/releases/latest 和发布资源 cmuxd-remote-checksums.txt）。未经身份验证的 GitHub API 每小时允许 60 次请求，正常使用时足够。如果用户遇到 403/429（共享 IP、CI 循环、反复重建），应设置 GITHUB_TOKEN（或 GH_TOKEN），脚本会在 API 调用和校验和下载请求中都转发该令牌。在指导用户集成 CI 时，请提及这一点。

Freestyle SDK 只需要 FREESTYLE_API_KEY；创建快照不需要 GitHub 凭据。setup.sh web 会以匿名方式克隆 manaflow-ai/cmux，因此也不需要身份验证；只有当用户明确想要对自己的 fork 执行 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

在仓库中迭代

整个构建器只有一个 TypeScript 文件：scripts/build-snapshot.ts。更新该文件时，请确保它与事实来源 repo/web/scripts/build-cloud-vm-images.ts 保持同步：

• 固定的 Agent CLI 版本（CLOUD_AGENT_TOOLS）。
• 默认 Node 主版本和 Bun 版本。
• Dockerfile 内容（freestyleBaseDockerfileContent、pythonOpenSSLCommands、toolInstallCommands、rootSetupCommands、imageSmokeTestCommands）。
• 快照创建调用的形式和恢复行为（waitForFreestyleSnapshotByName）。

cmux 修改其中任何一项时，都要在 cmux-freestyle 中更新对应常量、发布新版本；如果 URL/校验和约定有任何变化，还要更新脚本默认使用的 cmux 发布标签。

Freestyle CLI（npx -y freestyle vm ...）支持创建、列出、SSH 连接、执行命令和删除 VM，但不支持创建快照。因此，此脚本直接使用 freestyle SDK。请勿尝试将其替换为仅使用 CLI 的 shell 脚本。

规则

• 不要向用户保证共享快照 ID 对他们也有效。它不会有效。每位用户都必须使用自己的 Freestyle API 密钥运行一次 ./setup.sh。
• 不要将提供方 API 密钥、R2 凭据或任何用户专属内容打包进快照。Dockerfile 必须仅根据公共输入进行可复现构建。
• 不要让快照指向尚未发布的 cmuxd-remote。请使用已发布的 manaflow-ai/cmux 发布标签，以便 SHA-256 验证有可依据的基准。
• 不要放宽 Agent CLI 版本策略。规格必须使用精确的 semver 固定版本；范围和 latest 会被有意拒绝，以确保每次重建都可复现。
• 迭代时不要使用 manaflow 的 Freestyle 账户。请使用个人 Freestyle 账户；manaflow 的快照生命周期由仓库内的构建器和 cmux 镜像清单管理。