Repository navigation
feat: add Fly.io Sprites and boxd session environments - #21257
Conversation
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: both providers sit behind Notes
[DESIGN-REVIEWED] 5985659 Description read[DESCRIPTION-READ] 6e0c7b295570593d5243f5330868787ac7fc90cac414f1e13a403a15c71639f0 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks: both providers are new options next to Coder and stay hidden behind What this change shipsInventory (10 items) — 10 justifiedIntent: let a chat run its workspace on a Fly.io sprite or a boxd machine instead of needing a Coder deployment. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 5985659 Description read[DESCRIPTION-READ] afa5b550262d784e29b97ab6b37ac8fc9bde27473080402405aa444f932aee5b That sha256 names the PR description this verdict read. Recompute it with |
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing blocks. The blind reader read every primary control correctly and said they would use it: the provider cards, "+ Add Sprites profile", the token field, "Check Sprites connection" and the "Run this chat on" menu. All changed states are shown in screenshots. Notes
[UX-REVIEWED] 5985659 Description read[DESCRIPTION-READ] f29a780e07963cb8bb9cadabf3dd5a717791a869029bcaf6f8ba570fca43c1de That sha256 names everything this verdict read: the PR description, plus the 16 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findings (all downgraded on adjudication)GPT 6.1 flagged blocking issues on This comment is updated in place on each push. Review detailsBLOCKING -- src/kiro_crew/coder/retention.py:306 -- An unrelated VM registry failure blocks local History resumes
Adjudication (Opus 5.5) — is blocking on each finding proportionate?F1 is downgraded: a corrupted registry file is rare, the error is loud and names its cause, the feature only runs in dev mode, and the suggested fix would itself risk deleting remote workspaces. F1 — MEDIUM at most (loud, recoverable, dev-mode only). The failure needs all of these:
When it happens, the user gets a 503 whose message names the cause, "the boxd session registry is unreadable" ( The real fix is not cheap. Gating on the durable choice ( False positive or not applicable? A repository writer can comment: |
6b91cb7 to
47b1810
Compare
dfdfe7f to
efcc147
Compare
5da3123 to
9c027ca
Compare
efcc147 to
7a1da56
Compare
|
UX: token-save error reads as two messages (span=2a23805ff756): kept, rebut. The order is the one an earlier UX round asked for: the step this card can do (pick another secret name under Advanced) comes first, and the server's own reason follows as the explanation. Rewording or mapping the server's text would mean this card maintaining a copy of every refusal the secrets API can return; that text belongs to the secrets handler and is shared with Settings > Secrets. When the server gives no reason, the card shows the retry step instead, so the two never compete with each other on that path. |
|
UX: switch label says stop, the lines say hibernate / not stopped (span=4a8f74d08a63): kept, rebut. The label and its first line are p1's (#19833) setting, which is about stopping Coder workspaces; ruling 1 keeps that setting as it is. The previous UX round asked for exactly this layout (one switch, same on every tab, one line per provider underneath), and those lines say what the same switch means for each provider: boxd machines hibernate (which is boxd's stop that keeps the disk) and sprites need no call. Renaming p1's switch label from this PR would change a stack-owned string under every other provider PR. |
|
HOLD at 9af0ba6. This needs a human reviewer, and it cannot be approved yet in any case. What blocks approval:
The two UX Watch items have replies on this head. Opus and GPT report no findings, and checks are green. — crew-pr-reviewer (r113) |
|
Screenshot evidence for head ea0bcfc, referenced from the PR description. |
|
Screenshot evidence for head 54fd530, referenced from the PR description. |
|
Screenshot evidence for head 9fd1c5e, referenced from the PR description. |
|
GPT 6.1 Review on
|
|
Opus 5.5 Review on
|
|
GPT 6.1 Review on
|
|
History note for |
|
HOLD at 0756cae. This needs a human reviewer, and it cannot be approved yet in any case.
Opus and GPT report no findings, the earlier GPT and Opus rounds are answered and fixed, and checks are green. — crew-pr-reviewer (r124) |
|
Restacked onto credentialed git New since
Everything else in the range-diff is context from the new base, the regenerated |
|
Re GPT 6.1 on
|
|
Pushed
|
|
Re GPT 6.1 on
|
|
Restacked onto credentialed git
Commit 1 differs from |
|
Re GPT 6.1 on
|
|
Re Opus 5.5 on
|
|
HOLD at 491a961. This cannot be approved yet, and it needs a human reviewer.
The GPT 6.1 and Opus findings since r124 were each fixed with a test. Opus and GPT report no findings on this head, and checks are green. AI findings judged non-blocking:
I read the description, the review threads and the sensitive entry points. I did not run tests. — crew-pr-reviewer (r134) |
|
Import edits: New test: Checks on |
|
Re crew-pr-reviewer r134, untracked follow-up: the move of |
|
GPT 6.1 finding on 8ee2572 (run 40891520022, default_profile checked against the submitted lists): fixed in 052214d, folded into commit 2.
Tests (each fails with the fix reverted):
|
|
GPT 6.1 on a41b604: F2 (upheld, fenced; a token-only save brings back a stale readiness result) is fixed in a433763, folded into commit 2. |
Fly.io Sprites and boxd join Coder as session environment providers. Both share one persistent-VM lifecycle on the Coder registry, lock and archive generation, and the Sprites API token is saved to the vault, never to config.
- A refused revive of a session that was never closed no longer puts its remote workspace back on retention. - A sprite or boxd start reports its provisioning stage on the starting session, not the owner whose machine it reuses. - The shutdown switch shows its stored value and stays usable to turn off when no profile is left, since shutdown still acts on registered machines. - The creating account's fingerprint is saved with a VM reservation, and the create refuses under any other credential, so a create cut short before its record was bound never orphans the machine. - The core handlers facade manifest names _keep_vm_profiles. - Two profiles sharing a secret name with different typed tokens are refused before any write. - A reopen whose registry write fails is refused instead of publishing a tab whose deadline still stands. - A Sprites or boxd list write may not drop the profile the default names. - A whole save's default profile is judged on the merged section under the write lock, so a save that omits the Sprites or boxd list may default to a profile that list keeps; the pre-lock normalizer (and the change card's pre-check) checks only the default's shape. - Changing only a Sprites token drops the last readiness check, so a save never shows an earlier "accepted" for a token that was not checked. - The default-profile checks read saved profile ids through the loaders, so a hand-edited row with a non-string id no longer fails a write with a 500. - The provider-neutral pieces move out of coder/ into a new session_environments/ package, unchanged: persistent_vm.py (with SessionResourceRegistry), the provider routing and move guard (routing.py), and the sprite and boxd branches of browse and retention. coder/ keeps Coder's own code, and a test keeps sprites_session and boxd_session from importing those pieces from coder/.
|
GPT 6.1 on a433763: F1 (fenced; an unhashable hand-edited profile id crashes |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved on behalf of the watch holder (bolichen). Design and First Principles pass on this head (or skipped / author override), UX skipped or pass, no conflict, no open change request.







































Problem / Motivation
Goal: Let a chat run its workspace on a Fly.io sprite or a boxd machine, the same way it can already run on a Coder workspace.
Session Environments run a session's files, builds, tests and shells on a Coder workspace, so only teams that already operate a Coder deployment can move work off the gateway. A developer with a Fly.io account or a boxd login has no way to give one session its own machine.
Why it matters
Sprites and boxd are hosted VMs with no deployment to run: a token or a CLI login is all the setup. Each session gets a VM that keeps its disk, sleeps when idle and bills little while it waits, so isolating heavy or risky work no longer requires a Coder server.
Not a goal
What changed (motivation → approach → change)
Developer flag. Like Coder, Sprites and boxd sit behind
KIROCREW_DEV_MODE: with it off, the picker offers no profile, a bound session starts on the gateway, retention builds no VM provider and no sweeper starts.A chat picks a Sprites or boxd profile in the composer chip, and gets its own VM. Engine, memory and git credentials stay on the gateway; the existing worker, relay and git proxy run unchanged on the VM.
src/kiro_crew/sprites_sessionAuthorizationheader), exec shell with the worker secret on stdin, worker dial, PTY terminal bridgesrc/kiro_crew/boxd_sessionboxdCLI wrapper on the gateway's ownboxd auth login, exec shell, launchsrc/kiro_crew/session_environments,src/kiro_crew/codercoder/keeps only Coder's own code:persistent_vm.py(one registry and lifecycle for both VM providers),routing.py(a profile id to its provider, and the guard that keeps a session on the provider it started on), and the VM branches of browse and retention, which Coder's launch, retention and browse callsrc/kiro_crew/config,config-baseline.json,src/kiro_crew/docs,src/kiro_crew/change_card_catalog_kinds.pysession_environments.sprites_profilesandsession_environments.boxd_profiles(at most 20 each), their baseline and settings registry, classed code-execsrc/kiro_crew/dashboardsrc/kiro_crew/providers,src/kiro_crew/slackwebsite/src/pages,website/src/components,website/src/api,website/src/assetswebsite/src/i18n,website/src/test,test,docsproviders.mdandconfig.mdsections, feature-map rowLifetime follows the Coder rules. A VM's name and registry row are written before the create call, so a failed create is reclaimed later. A VM answering under a recorded name with a different id is refused; one deleted outside Kiro Crew is replaced, and the model is told the workspace is empty. Archive runs under Coder's per-session lifecycle lock: a boxd machine is hibernated and given a
delete-aftertimer, a sprite goes cold by itself, and the sweep deletes due rows after re-checking identity. A History reopen cancels that deletion, identity-checked, before the tab opens, or refuses for a retry (also when its registry write fails); nothing is created or woken. The sweeper keeps running while a Sprites or boxd registry exists, so removing every profile still deletes archived VMs. Each sprite row records its token's vault key and a one-way token fingerprint: a changed key, another account's token or another boxd login is refused, and no command, terminal or deletion goes out under it. A blank working folder means the VM's home: each start reads$HOMEfrom the VM, refuses one that is not absolute and records it, so Files and the terminal open the same folder. Those views never create a VM.VM rows live in their own
SessionResourceRegistry, not Coder'sWorkspaceBindingRegistry, whose rows are workspaces on one deployment (id, owner, organization, template); a VM row holds only the provider's VM id and home and a sprite's token key.One profile id may not name two of the three providers: every save checks it under the config lock, the picker leaves such an id out, and a session whose recorded provider does not match its profile id is refused rather than moved. A
coder-tagged session that already holds a sprite or boxd machine is refused too, so an archived VM is never left due for deletion behind a moved session. A session whose profile was removed is refused, never started on the gateway. A Sprites or boxd list write may not drop the profile the default names. One Save stores the profile, then the Sprites token (a masked field) in the vault, so a refused profile never overwrites a saved token, which never enters config. The readiness check lists one sprite per profile and runs oneboxd machine list, waking nothing.The spawn audit gains two individually justified entries: the boxd lifecycle CLI (
boxd_session/cli.py::_run: fixed verbs, validated names, stdin closed, no shell) and the in-processsprites_session/terminal.py::main; no module exemption, no baseline change.What survives a disconnect
The engine runs on the gateway, so any disconnect ends the in-flight turn: it is not re-run, and the user presses Continue. A guest worker with no authenticated gateway message for 600 s stops itself.
stop_on_shutdownis on, else left runningdelete-aftertimer clearedBackwards compatibility
Compatible: both lists are new, optional and empty by default, a stale Settings tab or change card that omits them keeps each valid saved entry, and a stored choice runs on the provider it recorded, so existing configs and sessions behave as before.
Removes nothing: every change adds a provider branch beside the Coder path; no key, route, tool or setting is renamed or withdrawn.
Tests
test/test_sprites_session.py,test/test_boxd_session.py,test/test_boxd_cli_discovery.py,test/test_sprites_boxd_failures.py: create, dial, exec, terminal bridge, identity refusal, replacement after outside deletion, bounded failures; a reopen whose registry write fails is refused.test/test_persistent_vm_retention.py,test/test_persistent_vm_cleanup.py,test/test_persistent_vm_guest_isolation.py: archive stamping, sweep under the lifecycle lock, reopen clearing the stamp, failed-create reclaim, a removed profile's sprite deleted with its recorded token key, a registry row with an unknown field still loading.test/test_archive_schedules_retention.py: a History reopen cancels the pending deletion before publishing, and one that cannot cancel it is refused (reopen_retention_failed) and re-archived; intest_boxd_session.pya failed cancellation is reported and a same-name replacement machine is left alone.test/test_coder_boot_activation.py: the sweeper starts from a registry alone, sweeps and hibernates only owned VMs, stays on when a registry cannot be read, and starts once when a configuration save lands during the probe.test/test_session_environments_vm_providers.py: the cross-provider id rule on every save, a row whose id moved to another provider refused at launch (acoder-tagged session holding a VM included), a stale Coder-only save keeping both lists, a list write that would drop the default's profile refused, one provider table for launch and retention, and every Sprites and boxd path unreachable withKIROCREW_DEV_MODEoff (fails with either new guard removed).test/test_session_environments_start_gate.py: removing the last Sprites or boxd profile never starts that session locally. Plus provider cases intest_coder_retentionand the twotest_spawn_auditentries.SessionEnvironmentsCard(provider tabs and hint line, the Sprites shutdown line, the boxd line and its accessible description, token field saved with the profile in one Save and its secret name under Advanced, machine size, check rows, shared "In use by a chat" row),SessionEnvironmentChip(provider marks), settings coverage.test/test_session_environments_import_boundary.py:sprites_sessionandboxd_sessionimport none of the shared pieces fromcoder/, and none of them is defined incoder/again.tsc, the fulleslint src/,i18n:check; vitest for the touched frontend files; Semgrep with main as the baseline. On this head: the scoped backend run (6,468 passed; the 2 failures, in files this PR does not touch, come from the local Python 3.13 and not from this change).Manual verification
Screenshots / video
Real components in a Storybook harness, every API call answered from fixtures (no gateway, no VM).
Sprites tab: the one shutdown switch, shown the same on every tab with a line per provider under it (boxd hibernated, sprites never stopped), the provider hint line, a saved profile with its "Sprites API token" field, a token already saved, and its secret name under a closed "Advanced: secret name", the readiness check, and both session sprites listed as "In use by a chat" (one archived, with its deletion time):
First-time setup: a new Sprites profile before it is saved, with no token yet; the one Save stores the profile and a pasted token together:
Every Sprites setup step, and the secret-name field opened under "Advanced: secret name" with its line saying it is the name the token is stored under in Settings → Secrets:
Every boxd setup step:
The Coder tab under the provider picker, with nothing saved for Coder:
Sprites tab with a token the check rejects: the failure shows inline on that profile's row:
Save with a token the server refuses (the fix on this card comes first: another name under "Advanced: secret name"; then the server's own reason; the "token is saved" line is withdrawn, the typed token stays, and no configuration is written), and the saved-token list cannot be read (with Retry):
boxd tab: the same shutdown switch and lines, machine size on a profile without a snapshot, the readiness check, and the same "In use by a chat" rows:
A boxd profile with a snapshot: the machine size is disabled, since a snapshot keeps its own size:
Composer chip with a sprite chosen: each provider's mark, and the check on the selected row:
Light theme
Related Issues
Part of #10433
no linked issue: this provider PR closes nothing; #10433 stays open until the remaining Session Environments providers land.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)