Cloud VM agent login onboarding

AU
18d ago
+836-53

Summary

  • Gate Cloud VM agent launches on actual CodeRouter account discovery or valid native credentials for Codex, Claude, OpenCode, Pi, and Hermes.
  • Guide accountless users through shared CodeRouter access versus native VM login, including VM-display browser login and headless codex login --device-auth.
  • Keep API-key, device-auth, status, help, logout, older-image, direct OpenCode, and Hermes peer-agent paths backward compatible.

Changelog

  • Fixed: Cloud VM agent launches now provide localized shared-account or native-login onboarding without forwarding native browser callbacks to the Mac.

Testing

  • PATH=/opt/homebrew/opt/python@3.13/libexec/bin:$PATH bun run test tests/vm-agent-login.test.ts — 31 passed, 0 failed, 89 assertions.
  • PATH=/opt/homebrew/opt/python@3.13/libexec/bin:$PATH bun run test tests/vm-devbox-image.test.ts — 40 passed, 0 failed, 470 assertions.
  • PATH=/opt/homebrew/opt/python@3.13/libexec/bin:$PATH bun run test tests/vm-guest-cli.test.ts — 92 passed, 0 failed, 790 assertions.
  • PATH=/opt/homebrew/opt/python@3.13/libexec/bin:$PATH bun run test tests/vm-guest-browser.test.ts — 18 passed, 0 failed, 43 assertions.
  • bash -n web/services/vms/images/devbox/agent-config.sh web/services/vms/images/devbox/cmux-opencode — passed.
  • PATH=/opt/homebrew/opt/python@3.13/libexec/bin:$PATH bun test tests/vm-devbox-image.test.ts --test-name-pattern 'agent launch preflight explains missing auth' — 1 passed, 0 failed.
  • python3 scripts/verify-local.py — selected feature-flag check passed; no Swift files were selected.
  • git diff --check — passed.
  • ./scripts/localize-changes — 0 parity errors; the repository still reports 24,252 outstanding translation rows across existing catalogs.

Impact map

  • Source of truth: web/services/vms/guestCli.ts, web/services/vms/guestBrowser.ts, and web/services/vms/images/devbox/agent-config.sh.
  • User-facing copy: English and Japanese guest catalogs, with the existing English fallback for other web locales.
  • Regression coverage: web/tests/vm-agent-login.test.ts, web/tests/vm-guest-browser.test.ts, and the devbox preflight contract.

Commits

  • 9640e65f870 — regression coverage for account discovery, native login, browser targeting, shorthands, and backward-compatible commands.
  • 792ffb4f7ff — onboarding repair and compatibility fixes.
  • 92cb13556fc — localize the account handoff fallback when the guest message helper is unavailable.
  • f15eefe48ea — clear the persisted native-mode marker after agent logout and cover the regression.
  • 4d942c2f73f — complete native cleanup, shorthand, browser, and guest-agent routing repairs.

CI note

  • The latest required CI run also reports the pre-existing checked-in devbox manifest source mismatch (01cae36958be… versus 0d7685f46539…) in the contract and Web tests. bun run devbox:manifest:check reproduces it locally; none of the changed files are image manifest sources.

Residual risk

  • Live Cloud VM, CodeRouter account state, and an actual Chrome OAuth callback were not exercised from this checkout; the focused suites use deterministic VM and browser doubles.

Summary by CodeRabbit

  • New Features
    • Added Hermes to the supported local and remote agent commands.
    • Added sign-in guidance for shared accounts and native authentication, including browser and device-based options.
    • Agent commands now check sign-in readiness and show guidance when authentication is needed.
    • Codex sign-in can open in the VM’s browser when available.
    • Native agent sign-in avoids using generated CodeRouter settings while preserving unrelated provider settings.

[!NOTE]
Medium Risk
Touches VM agent auth routing, credential/env handling, and OAuth browser behavior; mistakes could block launches or leak route placeholders into native login, but changes are heavily tested and preserve explicit login/help paths.

Overview
Cloud VM coding agents now gate launches on real auth: shared CodeRouter accounts (edge discovery) or native credentials on the VM, with guided onboarding when neither is ready.

cmux agent login (plus login/auth/setup aliases) walks users through shared CodeRouter (cmux auth login on the Mac) versus native sign-in on the VM, with localized copy in EN/JA. Native mode strips CodeRouter placeholders from the child environment, skips generated OpenCode/Pi route config, and persists a .native marker only after a successful login; logout clears it.

Hermes is added alongside claude/codex/opencode/pi in guest CLI, cmux vm agent, and help strings. Devbox agent-config.sh centralizes preflight, native/shared routing, and wrapper functions; cmux-opencode and the guest shim delegate to the same path for older images.

OAuth in the VM: when CMUX_BROWSER_TARGET=vm, cmux-open-url opens Chrome on the VM display instead of forwarding loopback callbacks to the Mac; headless Codex stays on --device-auth.

Regression tests cover onboarding, browser targeting, shorthands, outage-tolerant discovery, and backward-compatible login/help/logout flows.

Reviewed by Cursor Bugbot for commit 68ed0fce62d173b4ebe26c284bafe1accaa3c509. Bugbot is set up for automated code reviews on this repo. Configure here.