feat(cloud): set up environments from chat, per-environment machine size, environment page in Settings
Links
- Stacked on #9706 (the
environments.machine_sizemigration). Merge that first; this PR retargets tomainafter. - Linear: SUPER-3149 (cloud onboarding), SUPER-3135 (machine size), SUPER-2747 (environment visibility)
- Demo recording: https://app.superset.sh/page/cloud-onboarding-set-up-environment-m5kl3a
Summary
This PR bundles three related pieces of cloud-environment work:
- Set up an environment from chat. A project with no cloud environment can get one, set up by an agent inside a cloud box, straight from the new-workspace screen or the Create environment dialog.
- Environments carry a machine size. New workspaces boot at the environment's size. The per-workspace size pickers are removed from the new-workspace screen and the Move to cloud dialog.
- The environment page lives in Settings. Its variables editor, size, and the "Manage environment" / "Save checkpoint" entry points all lead there.
Part 1: Set up an environment from chat (SUPER-3149)
Why
A new user who picks Cloud for a project with no environment gets stuck. "Environment" reads like Cloud vs Local, and nothing guides them to create one.
What / How
- New-workspace screen, when the selected project has no usable environment (none linked to the project, none opening on its repository):
- A green Set up Environment chip creates a personal environment from the project's GitHub repository (linked to the project). It then starts a cloud workspace whose prompt is the setup request followed by the
superset:environmentline for that environment. It ignores the draft's text, linked issues and attachments, and keeps the draft. - The setup runs with the selected agent, or the default cloud agent (the last one chosen, else the first offered) when "none" is selected. If no agent is available, it says so instead of starting a bare workspace.
- Send does the same, with the typed message followed by a sentence that loads
superset:environmentinside the box ("you are already in a box on that environment, so set it up here"). - If the workspace fails to start after the environment was created, the screen remembers that environment for that project as still waiting for setup, without waiting for the environment list to refresh. The chip stays, and the next Send or chip click retries on the same environment instead of creating another (
planEnvironmentSetup, unit-tested). - If the GitHub App can't see the repository, it falls back to the Create environment dialog, passing the typed message and the selected agent along. Cancelling the dialog keeps the draft; once the agent starts, the draft is cleared. Attachments and linked issues don't go through this path.
- If creating the environment is refused for usage (for example the environment limit), the error offers Open billing.
- A failed environment list now blocks with "Could not load environments" instead of looking like "no environment".
- A green Set up Environment chip creates a personal environment from the project's GitHub repository (linked to the project). It then starts a cloud workspace whose prompt is the setup request followed by the
- Create environment dialog:
- Start agent (was "Get started") starts the setup in a cloud workspace instead of a local chat, with the agent selected on the new-workspace screen, else the default cloud agent.
- Adds Skip & save and an explanatory note.
- Links the caller's project only when the chosen primary repository is that project's (
projectToLink). - If the workspace fails after the environment exists, the dialog closes with "Saved X, but its setup workspace could not start", plus an Open billing action for usage refusals, so a retry can't make a duplicate.
- State resets on every open, and a ref guards against double starts.
- In a cloud chat whose environment was never checkpointed (
sourceKind: "image"), the environment's creator sees a chip that inserts the setup request plus thesuperset:environmentline into the composer.
Key decisions
| Decision | Choice | Rationale |
|---|---|---|
| Who sets the environment up | An agent inside a cloud box on the new environment | That's the workspace being configured. The skill is named explicitly, with an "already in a box" clause, because superset:environment is written for driving a box from outside. |
| Environment scope | Personal | Matches the existing dialog; the user can share it from the environment page. |
Part 2: Environments carry a machine size (SUPER-3135)
What / How
- API (additive only):
environment.createtakes an optionalmachineSize.environment.updatetakesmachineSizethat may benull, which resets to the org default.- Both validate the size against the organization's plan.
cloudWorkspace.create:- A caller that names no size boots at the environment's size.
- If the plan no longer offers that size, it falls back to the org default.
- A size the caller names explicitly is still validated and refused if not offered.
- Who can change it: on a shared (organization) environment, only its creator or an org admin/owner can change the size, since it sets the bill for everyone who boots on it (FORBIDDEN, "Admin access required", via the existing
verifyOrgAdmin). - Automations: they now pass their own size only when they have one, so the environment's size applies otherwise. The automation size picker gains an "Environment's size" option that sets it back to none.
- Devs:
launchTasknever passed a size, so Dev workspaces also boot at the environment's size once one is set. - Save as environment: a new environment saved from a workspace copies the source environment's size.
- Desktop:
- A Machine size select on the environment page: "Organization default (…)" plus offered sizes, and a stored size the plan dropped shows as "(not on your plan)".
- The size pickers are removed from the new-workspace screen (including its
#mention menu) and the Move to cloud dialog.MachineSizePickerPillis deleted. - The size each user last picked per project is no longer used: workspaces boot at the environment's size, and the create-defaults store's v4 migration drops the remembered size from saved data.
Compatibility (trpc-compat)
- Inputs: new fields are optional, no existing field is tightened, and error codes are unchanged.
- Behaviour: omitting
machineSizeoncloudWorkspace.createnow means "the environment's size, else the org default". Every existing environment row isnull, so nothing changes until someone sets a size. The input JSDoc and the SDK type docs are updated to match. - Released desktop builds always send a size (the one each user last picked, else the org default), so their users keep booting at that size, not the environment's, until they update. No server change can fix that without breaking callers that mean an explicit size.
environment.promoteonto a shared environment now returns FORBIDDEN ("Admin access required", an error clients already show) to a member who neither created nor administers it. This is a deliberate tightening.- CLI and MCP help no longer call
mediumthe default size. - Older APIs strip the new
update.machineSizefield, so the desktop setting quietly does nothing there. The API deploys on merge, well before a desktop release.
Part 3: Environment page in Settings (SUPER-2747 and follow-ups)
- New route:
/settings/environments/$environmentId.- The old
/environments/$environmentIdroute is now abeforeLoadredirect, because the app restores its last route at boot. - Settings → Environments rows open it. The separate variables-only screen is removed, and its editor (add / .env import, edit, delete, search, sort) moved onto the environment page.
- The old
- Environment picker: shows each environment's repositories and an Edit ‹name› item.
- Cloud workspace
…menu:- Manage environment.
- Save checkpoint: a confirm dialog that calls the existing
environment.promotewith the workspace'senvironmentId. It's disabled until the workspace is ready and while a save is in flight, and it refreshes environments and the workspace list afterwards. - Who can save one (API change):
environment.promoteonto a shared (organization) environment now needs its creator or an org admin/owner, the same rule as its size. Before, any member who could see it could replace the checkpoint everyone boots from. The menu hides the item for everyone else. A personal environment is unaffected.
- Sidebar right-click: Manage environment. It's looked up only while the menu is open, so closed rows cost nothing.
- Translations: the moved variables editor's strings are now translated, its "Added" date uses
formatDate, andCreateEnvironmentFlow,EnvironmentViewandsettings/environmentsare added to the i18n enforced dirs.
Manual QA Checklist
Done in the desktop dev build against the local API, with real mouse and keyboard input (xdotool) and request bodies captured over CDP:
- The chip appears only for a repo with no environment, and stays while typing.
- Chip click →
cloudWorkspace.createprompt is exactly the setup request. Send → typed message + thesuperset:environmentsentence with the new environment's URL. - Create environment dialog: the note and Cancel / Skip & save / Start agent show on the last step. Start agent sends name "Set up ‹repo›", agent
claude, nomachineSize, and the setup prompt. Skip & save creates the environment, closes the dialog, and sends no workspace create. - Picker shows repositories under each environment; Edit opens the environment page in Settings.
- Machine size select: choosing Large saves
large, choosing the default savesnull(read back throughenvironment.get). - Settings → Environments row → environment page inside Settings, with the variables editor; the Add sheet opens.
- The old
/environments/<id>URL on reload lands on/settings/environments/<id>. - Sidebar right-click on a cloud workspace shows Manage environment → its environment in Settings.
Not verified end to end:
- A cloud box actually booting and running the setup skill. This sandbox's local API can't start cloud workspaces (it can't decrypt the copied GitHub token, and its Vercel credentials are fake), so every cloud start here ends in that error toast.
- Save checkpoint, the in-chat chip, and the
…menu items: cloud workspaces never get past "Starting" in this sandbox. - Fixes made after the review passes were exercised by tests and typecheck, not re-clicked: the onboarding retry, the default agent, the chip prompt, the dialog failure path, Move to cloud without a size, automations' size, the size permission, the creator-only chat chip, and the second review's fixes (dialog agent and draft, Save checkpoint gating, billing action, automation size picker).
Testing
tsc --noEmitinapps/desktop,packages/trpc,packages/sdk,packages/dbbunx biome check(clean)bun test apps/desktop/src/renderer/{routes/_authenticated,stores,lib/persisted-keys}: 9610 pass (whole desktop suite)bun test packages/trpc/src/router: 655 pass.packages/cli: 513 pass,packages/mcp: 26 pass, andtscin both. New: boots at the environment's size; falls back when the plan stopped offering it (asserts the second lookup); refuses an explicit unoffered size;environment.updaterefuses a non-creator, non-admin on a shared environment, resets withnull, and refuses an unoffered size;environment.promoterefuses a non-creator, non-admin replacing a shared environment's checkpoint (fails without the check).planEnvironmentSetuptests: retry before and after the list catches up, a different selected environment, another project, and the dialog fallback.bun test packages/i18n: 172 pass (including the three newly enforced dirs)bun run check:i18n: all 17 locales fully translated
Known limitations
- The in-chat chip stays until a checkpoint is saved. Each click appends another copy of the setup request, and a checkpoint saved somewhere other than this window (for example by the agent through the CLI) only hides it once the environment list refetches.
- The remembered "waiting for setup" environment lives only while the new-workspace screen is mounted.
- No unit test for the automation size rule in
cloudDispatch.
Deployment / Rollout
- Ordering: #9706 (migration) deploys first. Then this PR: the API ships on merge, and the desktop changes go out with the next desktop release.
- Rollback: revert this PR. The column stays and is ignored, so no data cleanup is needed.
Summary by cubic
Bundles three related pieces of cloud-environment work: setting up an environment from chat, per-environment machine size, and moving the environment page into Settings. Stacks on the environments.machine_size migration and must merge after it; API changes are additive, and released desktop builds keep sending their own size until updated.
Set up environments from chat
- A project with no usable environment can create one from a Set up Environment chip or from Send; an agent inside a cloud box on that environment runs the setup, and a failed workspace start retries on the same environment instead of creating another.
- Setup uses the selected agent or the default cloud agent, and the Create environment dialog's Start agent now starts setup in a cloud workspace with an explanatory note and Skip & save.
- The Send-to-dialog fallback keeps the draft and clears it once the agent starts, cloud submit waits only while projects load, and a cloud chat on an environment without a checkpoint shows a setup chip to its creator.
Machine size and environment page
- Environments carry a machine size; cloud workspaces boot at it, falling back to the organization default when the plan no longer offers it, and the per-workspace size pickers are removed from the new-workspace screen and the Move to cloud dialog.
- Automations without their own size boot at the environment's size; changing a shared environment's size, or saving a checkpoint onto it, requires its creator or an org admin/owner.
- The environment page moves to
/settings/environments/<id>(the old route redirects) and hosts the variables editor, size selector, and Manage environment / Save checkpoint entry points; Manage environment also shows in the cloud workspace's…menu and sidebar right-click.