在自有 Freestyle 账号上构建 cmux…

当用户想用自己的 Freestyle API key 生成一个 cmux 后端可启动 Cloud VM 的 Freestyle 快照时，用独立脚本从零构建并接入 cmux。

适用场景

解决思路

1. 克隆独立仓库并运行安装脚本：`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`。
2. 用 `./setup.sh snapshot`（默认子命令）生成快照，可用 `--release <tag>` 或 `CMUX_RELEASE_TAG=<tag>` 固定 cmuxd-remote 发布版本（默认最新稳定版），用 `--name <name>` 或 `CMUX_FREESTYLE_SNAPSHOT_NAME` 设置快照名，用 `--skip-cache` 或 `CMUX_FREESTYLE_SKIP_CACHE=1` 强制干净重建，用 `--codex-spec none`、`--claude-spec none` 等去掉个别 agent CLI，用 `--json` 输出机器可读结果（人类可读路径会打印 `FREESTYLE_SANDBOX_SNAPSHOT=sh-...`）。
3. 构建内容需镜像仓库内 builder 的 `freestyleBaseDockerfileContent`：`ubuntu:24.04`、`C.UTF-8`、相同 shell 包集合、cmux 浏览器代理所需的 Python/OpenSSL shim；从固定的 `manaflow-ai/cmux` GitHub release 下载 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` 运行 `cmuxd-remote serve --ws --listen 0.0.0.0:7777 --auth-lease-file ... --rpc-auth-lease-file ...`，映射 Freestyle 端口 `443 -> 7777`。
4. 镜像需运行与仓库内 builder 相同的 smoke test，让失败在快照构建时暴露而非在运行中的 VM 里。
5. 需要完整自托管时按顺序使用四个子命令：`./setup.sh doctor`（校验工具、环境、Freestyle key、GitHub release）、`./setup.sh`（在用户 Freestyle 账号下生成快照）、`./setup.sh web --snapshot sh-xxxxxx`（克隆 manaflow-ai/cmux、写 web/.env.local、启动 Docker Postgres）、`./setup.sh home --ref feat-ink-rewrite`（安装 cmux-home Ink TUI 总部视图）。
6. `web` 子命令会把 `manaflow-ai/cmux` 克隆到 `~/cmux-freestyle-cmux`，把 Freestyle + Cloud VM 环境变量写入 `web/.env.local`，运行 `bun install`，并启动 per-worktree 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`）。
7. `home` 子命令在 `~/cmux-freestyle-home/ink` 安装并准备 `cmux-home` 的 Ink/TypeScript 移植版，TUI 连接本地 cmux 应用的 Unix socket，提供 Node-only 的 workspace 仪表盘和 Codex/Claude composer；Ink 移植版目前在 `feat-ink-rewrite` 分支，合并到 `main` 后切换默认 `--ref`；cmux-home 仓库根目录的 Rust crate 仍是功能完整的上游。
8. 若 `bun dev` 运行时环境中有 `FREESTYLE_API_KEY`（`home` 脚本会从用户的 `~/.secrets/cmux.env` 和 shell 导出），cmux-home 会在 workspace 列表下渲染 `Freestyle VMs (N)` 面板，每行显示 VM id、状态、快照 id 和年龄，同一选择光标可遍历两个面板。
9. 选中 VM 后：`enter` 打开 sandbox 工作流，创建运行 `freestyle-vm-ssh <vmId>` 的新 cmux workspace（该 helper 生成短期 Freestyle SSH 身份，通过 `vm-ssh.freestyle.sh` 建立 SSH 会话并带 `-R 31415:127.0.0.1:31415` 反向转发到本地 Subrouter AI 网关，以及 `-L` 转发常用开发端口 `3000`、`5173`、`8000`、`8080`，在 VM 内写 `~/.codex/config.toml` 把 `openai_base_url` 指向转发的 subrouter，然后进入登录 shell；同时在右侧打开 `http://127.0.0.1:3000` 浏览器面板）。
10. `ctrl+o` 打开 local-codex 工作流：在 TUI 的 `--cwd` 创建普通 cmux workspace，无 SSH，右侧浏览器面板打开 `https://<vmId>.vm.freestyle.sh`；Codex/Claude 在 mac 上针对本地 checkout 运行，VM 作为远程开发服务器。
11. `ctrl+x` 通过 Freestyle SDK 销毁 VM；在 `Freestyle VMs (N)` 标题上按 `ctrl+n` 用 `FREESTYLE_SANDBOX_SNAPSHOT` 创建新 VM。
12. 注意 Freestyle SSH 网关 `vm-ssh.freestyle.sh` 拒绝 `-R` 远程端口转发（`remote port forwarding failed for listen port 31415`），因此 `--reverse-subrouter` 是 opt-in 且仅适用于普通 Linux/macOS sshd 主机。
13. Freestyle VM 内 codex 的默认可用路径：`freestyle-vm-ssh` 通过 `tsadmin api POST /tailnet/-/keys` 生成临时 preauth Tailscale key（tag `tag:server`，1 小时过期），在 VM 内以 userspace networking（`--tun=userspace-networking`）运行 `tailscale up`，在 `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"`；cmux-freestyle 快照已内置 apt `tailscale` 包，首次启动约 6 秒，后续会话复用已有状态。
14. 可用 `--no-tailscale` 按调用禁用，用 `--subrouter-url <url>` 或 `SUBROUTER_REMOTE_URL` 覆盖 subrouter URL，用 `--tailscale-authkey <key>` 或 `TAILSCALE_AUTHKEY` 覆盖 auth-key；目前 Subrouter 只路由 Codex，在 Subrouter 支持 Claude/OpenCode 前 VM 内请用 Codex。
15. helper 需要 mac 上有 `sshpass`（`brew install hudochenkov/sshpass/sshpass`）且 `tsadmin` 在 `PATH` 上（`skills/tsadmin/scripts/tsadmin`）。
16. GitHub 认证：快照 builder 只访问公开 GitHub 端点（`/repos/manaflow-ai/cmux/releases/latest` 和 release asset `cmuxd-remote-checksums.txt`），未认证 API 每小时 60 次请求通常够用；若遇到 403/429（共享 IP、CI 循环、反复重建），设置 `GITHUB_TOKEN`（或 `GH_TOKEN`），脚本会在 API 调用和 checksums 下载时转发；Freestyle SDK 只需 `FREESTYLE_API_KEY`，快照创建不需要 GitHub 凭据；`setup.sh web` 匿名克隆 `manaflow-ai/cmux` 也不需要认证，只有用户明确想对自己的 fork `git push` 时才建议 `gh auth login`。
17. 把快照接入 cmux 后端：脚本打印快照 id 后，给用户环境变量块 `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 无法启动。
18. 临时 smoke test 用 `npx -y freestyle vm create --snapshot <snapshotId> --ssh`，在 VM 内确认 `cmuxd-remote version`、`cmux --help`、`claude --version`、`codex --version`、`node --version`、`bun --version`。
19. 迭代仓库时：整个 builder 是 `scripts/build-snapshot.ts` 一个 TypeScript 文件，更新时需与 `repo/web/scripts/build-cloud-vm-images.ts` 的 source of truth 保持同步——固定 agent CLI 版本（`CLOUD_AGENT_TOOLS`）、默认 Node 主版本和 Bun 版本、Dockerfile 主体（`freestyleBaseDockerfileContent`、`pythonOpenSSLCommands`、`toolInstallCommands`、`rootSetupCommands`、`imageSmokeTestCommands`）、快照创建调用形态和恢复行为（`waitForFreestyleSnapshotByName`）；当 cmux 改动其中任何一项时，在 `cmux-freestyle` 中同步对应常量、发布 release，并在 URL/checksum 契约变化时更新脚本默认的 cmux release tag。
20. Freestyle CLI（`npx -y freestyle vm ...`）覆盖 VM create/list/ssh/exec/delete 但不暴露 snapshot create，因此脚本直接使用 `freestyle` SDK，不要尝试用纯 CLI shell 脚本替代。
21. 规则：不要承诺共享快照 id 对他人可用（不会），每个用户都要用自己的 Freestyle API key 运行一次 `./setup.sh`；不要把 provider API key、R2 凭据或任何用户特定内容烘焙进快照，Dockerfile 必须仅由公开输入可复现；不要把快照指向未发布的 cmuxd-remote，使用已发布的 `manaflow-ai/cmux` release tag 以便 SHA-256 校验有锚点；不要放宽 agent CLI 版本策略，spec 必须是精确 semver pin，range 和 `latest` 会被故意拒绝以保证每次重建可复现；迭代时不要针对 manaflow Freestyle 账号运行，用个人 Freestyle 账号，manaflow 的快照生命周期由仓库内 builder 和 cmux image manifest 管理。

适用边界 · 注意事项

• 用户想为 manaflow 内部 cmux 开发推送新快照到 manaflow Freestyle 账号并更新 `repo/web/services/vms/images/manifest.json` 时，应继续使用 `repo/web/scripts/build-cloud-vm-images.ts`，而不是本技能。
• 用户没有自己的 Freestyle 账号或 `FREESTYLE_API_KEY` 时无法使用，因为快照按账号隔离，共享快照 id 对他人无效。
• 迭代时不要针对 manaflow Freestyle 账号运行，应使用个人 Freestyle 账号。