Launch a built-in agent when a cloud workspace is created
What
A cloud workspace can now be created with one of the built-in agents, and the agent starts inside the sandbox on first boot with the prompt you typed, the same way a local host launches an agent for a new workspace.
- Desktop: under Cloud, the agent pill offers the built-in presets (claude, codex, amp, gemini, …) instead of "No agent". With an agent selected and something to say (a prompt, a linked PR or issue), the create sends
agent,model,effort,modeand the context-built prompt. - Mobile: the agent chip and picker work for the Cloud target with the same built-in presets; the create sends the chosen agent.
- API:
cloudWorkspace.createacceptsagent(validated against the built-in preset ids) plusmodel/effort/mode; the provisioning job carries alaunch, and provisioning hands it to the sandbox asSUPERSET_SANDBOX_AGENT*environment (a 20 KB prompt survives the round trip; verified). - host-service (sandbox mode): after the server is listening, it runs the launch through
runAgentInWorkspace, the same pathagents.runuses, and writes/data/.sandbox-agent-launchedso a restart never repeats it. Promoting a sandbox to an environment strips the launch variables.
Custom agents (per-user configs in the cloud database) are SUPER-2127.
Two things the first real launch exposed
- The sandbox host had no agent presets. A laptop's host seeds the built-in presets the first time a client lists its agents; a freshly forked sandbox launches before any client asks, so the launch found no config matching
claude. The launch now seeds the defaults first, through the host's own seeder. - Forks had no model credentials of their own, and cannot be given the proxy. Placeholder keys plus egress-proxy routing only exist on sandboxes created from an image; Blaxel enables the proxy at creation only, and a fork is created without it. Trying to add routing afterwards with a spec update was worse than useless: the platform rebuilt the fork from its image, and the probe came back without
node_modules, xterm, or anything else the environment carried. So a forked workspace takes its model keys the plain way, fromANTHROPIC_API_KEY/OPENAI_API_KEYin the environment's variables, and host-service records the approval Claude Code would otherwise stop to ask for (last 20 characters of the key in~/.claude.json) before an unattended launch. Env-only spec updates are unaffected: forks keep taking their identity through the same update main uses.docs/cloud-sandbox-mismatches.mdrecords the finding.
Also: a cloud workspace's name is now generated with the prompt as data, not as a request; passed bare, an imperative prompt was getting answered instead of titled.
Review follow-ups folded in
Naming only treats a trailing period as a reply and states its 40-character tolerance; mobile derives one effective agent id under Cloud (a laptop-only preset shows, selects and launches as Claude); host-service claims the launch marker before launching and releases it on failure, and the key approval honours CLAUDE_CONFIG_DIR and never rewrites a .claude.json it could not parse; desktop skips the host-agent query for the cloud sentinel and bounds the assembled prompt; the signed provision route validates the agent id; a promoted golden drops the launch marker and the db-branch stamp; the release probe reads the stamp where it lives and checks both providers; the two older credential entries in the mismatches doc point at the fork exception.
Not in this PR
- Attachments on a cloud create still stay behind (they are written to a host that does not exist yet).
- Credentials: a forked cloud workspace runs its agent on the keys in the environment's variables (for the Superset environment, org keys rather than a personal one), not the user's Claude/Codex login. Image-created sandboxes keep the proxy injection.
Evidence
All of it against the real product, on this worktree's dev stack with the cloud-builtin-agents code in the API and a golden released from it (bun run sandbox:release, 134 s, every check green including a 200 from api.anthropic.com inside the fork).
- Desktop create, driven over CDP through the real new-workspace UI: device pill set to Cloud, environment Superset, agent Claude, prompt "Say hello, then list the top-level directories of this repo in one line.", submitted with ⌘↩. The workspace reached
readyand was named "Hello & List Dirs". - Inside the sandbox (checked over the provider's process API):
SUPERSET_SANDBOX_AGENT=claudeand the prompt in env,/data/.sandbox-agent-launchedwritten by host-service at boot, and aclaude --dangerously-skip-permissions <prompt>process running in/workspace. - In the desktop: the workspace opened on the adopted agent terminal, which showed Claude Code 2.1.257 answering ("Hello! Top-level directories: apps, docs, node_modules, packages, …", "Cooked for 7s") with no login prompt and no "use this custom API key?" prompt. The screenshot lives in the session report; it shows nothing but that pane.
- Naming: the same prompt produced "Hello & List Dirs"; an imperative bug report produced "Fix Terminal Reaper Flaky Test", and a Spanish one "Arreglar login".
- The test workspace was deleted through the app's own mutation afterwards; the probe sandbox by the release script.
- Mobile, on an iPhone 17 (iOS 26) simulator driven with Maestro against this worktree's stack: under the Cloud scope the expanded composer shows the agent chip (Claude) beside the Cloud and Environment chips; tapping it opens the Agent picker listing Claude (selected) and Codex; picking Codex closes the picker and the chip reads Codex; a prompt sent with it reaches the create path. The create itself was refused on the simulator with "Add an environment in Settings", which is correct for that session: the simulator signs in as the local dev admin, and cloud procedures require an internal account, so the mobile create could not be taken through provisioning here. Local (non-cloud) targets take exactly the code they took before: the agent lookup, the chip and the create payload only branch on the Cloud target.
What this does not prove: a prod workspace launching an agent, which needs this PR deployed (the launch env comes from the API) and org model keys in the prod Superset environment's variables (see below).