Cloud Secrets, one-step repo clone, and Cloud onboarding

AU
17d ago
+81521-6048

What this changes

A fresh cmux Cloud install can now go from keys to a working coding agent with one guided path. Cloud Secrets stores API keys and environment variables in the Mac Keychain, delivers them over the existing end-to-end machine link, and automatically syncs them to new or running machines. Values stay out of the control plane, command arguments, logs, telemetry and CLI output; only names, scopes and delivery fingerprints are surfaced.

The same PR adds the surrounding time-to-value path:

  • cmux vm secrets plus the Cloud Secrets sheet support all-machine, project and machine scopes, .env/stdin/shell import, rotation, revoke, delivery status and missing-secret preflight.
  • cmux vm clone <repo> --agent … handles repo URLs, GitHub auth, setup declarations, devcontainer secret names, workspace reuse, paused machines and warm starts. Warm restores clear snapshot-carried workspaces before a new checkout is created and are removed from the reuse pool if readiness or cleanup fails.
  • The first-run tour, Get Started card, Open Repository sheet, Cloud hints and empty states lead to a selected agent terminal. Open Repository defaults the guided agent path to Claude and uses an accent primary action, including when a sheet is already open.
  • Port sharing is one reconciled mutation path across CLI and GUI. --public --yes is non-interactive; narrowing to private removes or narrows every publication, retries only after an authoritative read, invalidates stale UI state when that read fails, and fails closed when the result cannot be verified.
  • Machine deletion updates the Cloud panel’s derived rows and usage count immediately. CLI labels, setup copy, workspace reuse, vm tree, vm doctor, readiness reporting and localization are included.

Trust and design decisions

Secret delivery is intentionally local-first: the Mac Keychain is the vault and the machine’s end-to-end receiver is the only delivery path. Claude Code’s custom-key approval is computed on the machine from its own env file and stores only the key suffix in its local config. Existing malformed or unreadable Claude config files are preserved. A failed warm cleanup destroys the newly restored machine before falling back cold, so a snapshot cannot leak its old workspace graph into the pool.

The UI follows the design references in cmux-design-references: first run for one next action and visible progress, settings for grouped scope and stable sheets, approvals for explicit public sharing confirmation, and status and progress for immediate, authoritative state.

Recommendation recorded for #13742: keep secret values device-local and end-to-end delivered, and require authoritative reconciliation before reporting a sharing change as complete.

Correctness review follow-up

A fresh independent read-only review found no blocker. The findings and resolutions are recorded in the review comment.

  • 2ca7cc44df98 fixes the high-severity partial-sync ledger bug: successful deliveries merge into the existing ledger, so held-back provider keys remain tracked for retry and revocation. A regression test covers the partial-delivery path.
  • 5e2ee7c47402 passes the authenticated team ID for GUI team publication changes, schedules a follow-up publication read when invalidation races an in-flight fetch, and approves every active Anthropic key suffix in Claude's local config.
  • The low-severity first-run project-scope observation is intentionally deferred: the early key step runs before repository selection, while project-specific requirements are checked during the project-aware clone step.

Validation

  • python3 scripts/verify-local.py --affected origin/main — 16/16 checks passed.
  • python3 scripts/localization_defaults.py and python3 scripts/localization_catalog.py check — 0 errors.
  • Swift syntax parsing for the changed app and CLI files — passed.
  • bun test ./tests/vm-provider-routing-guard.test.ts — 26 passed with Python 3.13; the host Python 3.9 lacks tomllib.
  • The focused malformed-config regression was red on fbfc990d0f8 and green on 5048728eac6.
  • Hosted CI is running for the post-review head 5e2ee7c47402; native app compilation and app tests are delegated to hosted CI per repository policy.

Changelog

Added: Cloud Secrets, one-step repository cloning and Cloud onboarding that get a coding agent running with the right keys.

Post-fix dogfood evidence

The exact post-fix fleet build at 921424f272c0 was exercised as the isolated tagged app issue-21028-cloud-secrets-r8.

  • A fresh machine received both provider keys over the end-to-end link; cmux vm secrets status --verify reported both current.
  • Claude Code started without the custom API-key confirmation prompt. Its local config gained only the suffix-derived approval entry computed from the machine's own env file; the deliberately fake test key then failed at the provider as expected.
  • A provider 503 during --public --yes left a disabled publication. cmux vm share --private --json converged to shared: none with no links; disabled/deleted rows no longer affect the audience plan.
  • r8 evaluator score: 8.25/10 overall (vault 8, first-run/clone 8, delivery/agent launch 9, sharing privacy/recovery 8).

The hosted PR checks for the merged head 222c451c47d9 are green: 27 passed, 0 failed, 0 pending. The PR remains draft pending human review and merge approval.

Explicit scope boundary

This PR ships a device-local Keychain vault and end-to-end delivery. A managed team vault is intentionally a follow-up trust mode requiring encrypted server storage, scoped permissions, audit history, rotation/revocation and recovery semantics. CUA driver/MCP registration and devbox image promotion remain on issue-18908 and are not included here; existing Cloud desktop images already contain the CUA runtime.

#13742 recommendation

Keep provider routing fail-closed: a user provider key must be routed directly before delivery and never enter the model router. Keep ports private by default; public sharing requires an explicit confirmation, and every narrowing or stop-sharing request must reconcile the authoritative publication list before reporting success. The first-run tour should provision eagerly so progress is visible and useful; cancelling removes only the machine created by that tour and never a reused machine.

Summary by CodeRabbit

  • New Features
    • Added Cloud Secrets management in the app and CLI, including scoped storage, .env import, machine sync, status checks, and repository-declared requirements.
    • Added repository cloning to Cloud with optional agent setup, a guided first-run tour, and setup checklists.
    • Added Cloud port inventory and sharing controls, plus CLI checks for port availability and agent readiness.
    • Added Cloud panel tips, keyboard shortcuts, and clearer failure details for agent runs.
    • Added repository opening from Cloud links, paste, and drag-and-drop, and warm-start snapshot management.
  • Improvements
    • Machine labels can now be used in CLI commands; parked machines wake before agent launches.
    • Failed terminal runs remain visible with status and diagnostic details, and already-open workspaces can be reused.
    • Added documentation for Cloud Secrets and opening repositories in Cloud.