Cmux Freestyle

cmux Freestyle

Use this skill when a user wants a Freestyle VM snapshot that the cmux backend can boot Cloud VMs from. It lives in its own public repo, `manaflow-ai/cmux-freestyle`, so anyone with a Freestyle API key can run one shell script and get back a FREESTYLE_SANDBOX_SNAPSHOT id.

Freestyle snapshots are scoped to the account that created them. A snapshot id from manaflow's account, or from any other user, will not work for a different Freestyle account. Every user has to run the setup script against their own FREESTYLE_API_KEY. There is no shortcut.

When to use

• User asks how to point their own cmux at Freestyle.
• User self-hosts the cmux web backend and needs a snapshot pinned to a known cmux release.
• User wants to rebuild the cmux Cloud VM image on their own Freestyle account.
• User wants to iterate on the standalone repo (cmux-freestyle) instead of the in-repo builder at repo/web/scripts/build-cloud-vm-images.ts.

For internal cmux development that pushes a new snapshot to manaflow's Freestyle account and updates repo/web/services/vms/images/manifest.json, keep using repo/web/scripts/build-cloud-vm-images.ts. This skill is the external-user path.

What it builds

A Freestyle snapshot from a Dockerfile that mirrors freestyleBaseDockerfileContent in the in-repo builder:

• ubuntu:24.04, C.UTF-8, the same shell package set, the Python/OpenSSL shim required by the cmux browser proxy.
• cmuxd-remote Linux/amd64 downloaded from a pinned manaflow-ai/cmux GitHub release, SHA-256 verified during the image build against cmuxd-remote-checksums.txt.
• /usr/local/bin/cmux symlinked to cmuxd-remote.
• Node.js, Bun, plus pinned coding agent CLIs (Claude Code, OpenCode, Codex, Pi).
• Linux user cmux with passwordless sudo.
• Systemd unit cmuxd-ws.service running cmuxd-remote serve --ws --listen 0.0.0.0:7777 --auth-lease-file ... --rpc-auth-lease-file ... on Freestyle port 443 -> 7777.

The image runs the same smoke tests as the in-repo builder, so failures show up at snapshot build time, not later inside a live VM.

How to use it

The repo is self-contained; no cmux checkout required.

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

Or the one-liner:

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

Useful flags / env on ./setup.sh snapshot (the default subcommand):

• --release <tag> or CMUX_RELEASE_TAG=<tag> pins the cmuxd-remote release. Default is the latest stable manaflow-ai/cmux release.
• --name <name> or CMUX_FREESTYLE_SNAPSHOT_NAME sets the Freestyle snapshot name.
• --skip-cache or CMUX_FREESTYLE_SKIP_CACHE=1 forces a clean Freestyle rebuild.
• --codex-spec none, --claude-spec none, etc. drop individual agent CLIs.
• --json emits a machine-readable result; the human path prints FREESTYLE_SANDBOX_SNAPSHOT=sh-... at the end.

The build takes 5 to 15 minutes depending on Freestyle's layer cache.

Full self-host bundle

./setup.sh is a dispatcher with four subcommands. Use them together when a user wants more than just the snapshot 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 is the Next.js dev env bootstrap: it clones manaflow-ai/cmux to ~/cmux-freestyle-cmux, writes the Freestyle + Cloud VM env keys into web/.env.local, runs bun install, and brings up the per-worktree Docker Postgres unless --no-postgres is set. Stack Auth keys (STACK_SECRET_SERVER_KEY, NEXT_PUBLIC_STACK_PROJECT_ID, NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY) are honoured if exported but optional. The script only needs git and bun (plus docker for Postgres).

home is the "headquarters view": it installs and prepares the Ink/TypeScript port of cmux-home at ~/cmux-freestyle-home/ink. The TUI connects to the local cmux app's Unix socket and gives end users a Node-only dashboard of every workspace plus a Codex/Claude composer. The Ink port currently lives on the feat-ink-rewrite branch; switch the default --ref once it merges to main. The Rust crate at the cmux-home repo root remains the full-featured upstream.

If FREESTYLE_API_KEY is set in the env when bun dev runs (the home script exports it from the user's ~/.secrets/cmux.env and the shell), cmux-home renders a second panel under the workspace list titled Freestyle VMs (N). Each row shows the VM id, state, snapshot id (the one from ./setup.sh snapshot), and age. This makes the TUI a single dashboard for both local cmux workspaces and the user's Freestyle Cloud VMs, with the same selection cursor walking both panels.

Selecting a VM enables the following actions on the row:

• enter opens the sandbox workflow: creates a new cmux workspace running freestyle-vm-ssh <vmId>. The helper script mints a short-lived Freestyle SSH identity, opens an SSH session through vm-ssh.freestyle.sh with -R 31415:127.0.0.1:31415 (reverse-forward to the local Subrouter AI gateway on 127.0.0.1:31415) plus -L forwards for common dev ports (3000, 5173, 8000, 8080), writes a ~/.codex/config.toml inside the VM that points openai_base_url at the forwarded subrouter, then drops into a login shell. Codex launched inside the VM in that shell routes through Subrouter on the user's mac. Also opens a browser pane on the right at http://127.0.0.1:3000.
• ctrl+o opens the local-codex workflow: a normal cmux workspace at the TUI's --cwd, no SSH, plus a browser pane on the right at https://<vmId>.vm.freestyle.sh. Codex/Claude run on the mac against the local checkout; the VM is treated as a remote dev server.
• ctrl+x destroys the VM through the Freestyle SDK.
• ctrl+n on the Freestyle VMs (N) header creates a new VM from FREESTYLE_SANDBOX_SNAPSHOT.

Freestyle gateway constraint. The Freestyle SSH gateway at vm-ssh.freestyle.sh rejects -R remote port forwarding (remote port forwarding failed for listen port 31415). The --reverse-subrouter flag is therefore opt-in and works only for ordinary Linux/macOS sshd hosts.

Default path for codex inside a Freestyle VM (works today): freestyle-vm-ssh mints an ephemeral preauth Tailscale key via tsadmin api POST /tailnet/-/keys (tag tag:server, expires in 1h), runs tailscale up inside the VM under userspace networking (--tun=userspace-networking), enables tailscaled's HTTP proxy + SOCKS5 server on 127.0.0.1:1055, writes /etc/profile.d/cmux-tailnet-proxy.sh so every login shell exports HTTP_PROXY/HTTPS_PROXY/NO_PROXY, and writes ~/.codex/config.toml with openai_base_url = "http://subrouter-team.tail41290.ts.net:31415/v1". Codex inside the VM then connects to the existing subrouter-team host on the tailnet through the local proxy, so all OpenAI traffic is routed through Subrouter's account scheduling. The cmux-freestyle snapshot already ships the apt tailscale package, so first-time bring-up is ~6 s end-to-end; subsequent sessions reuse the existing state.

Disable per-call with --no-tailscale, override the subrouter URL with --subrouter-url <url> or SUBROUTER_REMOTE_URL, override the auth-key with --tailscale-authkey <key> or TAILSCALE_AUTHKEY. Today Subrouter only routes Codex, so use Codex inside the VM until Subrouter adds Claude/OpenCode support.