docs(cloud): an agent guide for cmux vm without the app, run in CI

TE
6d ago
+384-9

Leo, 2026-10-30: "How about more cmux-platform audits, improvements, features, fixes, optimizations, polish, plus the ui that gets people (or agents) using it". Also 2026-10-29: "let's just get the cloud and its respective ui up to snuff".

An agent with no cmux app (CI, a headless agent, a Linux host) that read the cmux-cloud-vm skill was told "The Rust cmux has no vm scope." That's been wrong since cmux vm came back as a wrapper over the bundled cmux-vm API client. As a result, the skill showed no way to provision a machine without the app.

This PR adds skills/cmux-cloud-vm/references/headless.md, a short guide for that path:

  • getting a key into CMUX_VM_API_KEY, and keeping it out of arguments and logs
  • cmux vm ls, then cmux vm new --name … --idempotency-key …, and how to retry it safely
  • cmux vm exec VM_ID -- …, and what its exit code means
  • cmux vm pause, resume, and rm --yes
  • a table of exit codes, each with its next step

SKILL.md, references/commands.md and the skill's agent prompt drop the stale claim and link the guide.

The commands are checked by a test, not by hand: workers/cmux-vm/cli/crates/cmux-vm/tests/agent_doc.rs reads the guide and runs every cmux vm line in its sh blocks against a wiremock cmux VM API. It maps new, ls and rm the way cmux-tui/src/cli/vm.rs does, and a third test fails if those match arms leave vm.rs. VM_ID becomes the id new returned. The create and exec mocks match the exact request body and idempotency key, so a wrong name, command or timeout fails the test, and so does any line that is rejected or doesn't finish. It also fails when the guide stops covering list, create, exec, pause, resume and delete, and when new drops --idempotency-key. A second test checks that the guide's "exits 11" no-key claim is true. The cmux VM clients workflow now also runs when the guide changes, so a doc edit can't break the test unnoticed.

This stays off #27603 (in-process cmux vm, run --sync, scoped tokens). When #27603 lands, cmux vm token create can replace "get the key from the person", and its owner has been told.

Validation: on the Linux fast-checks runner, at the head's tree, cargo fmt --all --check, cargo test --locked -p cmux-vm --test agent_doc (3 passed) and cargo clippy --locked -p cmux-vm --tests -D warnings passed in workers/cmux-vm/cli.

Localization audit: the changed surfaces are an English agent skill and its reference. The skill directory has no other locales and isn't shipped UI. No Swift, Rust CLI or web strings change.

Risk: low. Docs, one new test, and one more workflow path trigger. The test runs the CLI against a mock, so it can't catch a server-side behavior change. The existing lifecycle tests already cover those routes.

Agent session: agent session

🤖 Generated with Claude Code