Dev Boxes
The computer the platform leases to a person, the two clocks that decide how long it lives, the proxy that is the only path to it, and the CLI tunnel that builds from a laptop instead.
The editor's development environment is a computer the platform leases to a person: a Kata microVM on the kata_dev island, booted from a full development image, reachable only through the platform, and snapshotted to S3 so work survives the box. This chapter covers the box, the lease, the proxy in front of it, the tunnel that runs the app's methods from it, and when a person's workspace ends.
#The Box
A dev box boots from the dev-box image: a pinned Node.js on a pinned Debian release, the system packages an agent and a person expect (Python, compilers, ffmpeg, ImageMagick, a headless Chrome), the global tooling, a warmed npm cache, and the control-and-command server as the entrypoint. Everything not specific to one app is baked in, so a cold boot spends its time on the app itself: cloning the workspace and installing its dependencies.
The box serves everything on one port: the app's preview, the control channel WebSocket for files, shell, search and agent actions, the language server WebSocket, and the hot-reload relay. It has no public ingress. Like every sandbox, its egress is the public internet only, it carries no cluster credential, and it resolves no internal name.
Each person with edit access to an app gets their own box, with their own working copy and their own dev database cloned from live. See Environments.
#Two Clocks
A dev box has two clocks by design, owned by two different parts of the platform.
The pod clock, owned by the orchestrator, is the outer bound: a Kubernetes deadline of 12 hours, a 10-minute boot budget that allows for a cold node pulling the image, and a shutdown sequence that fits inside the pod's grace period. On SIGTERM the box quiesces, settles, snapshots its home directory, and closes, with a budget for each phase so the snapshot always lands before the pod is gone.
The session lease, owned by the platform, is the policy: a box lives 30 minutes past the last evidence that someone is using it. Two things renew the lease: the editor's keepalive, sent every 30 seconds while its tab is visible, and every agent inference call. An unattended agent build renews its own lease every turn and releases the box a lease-length after it stops. A sweep reclaims boxes whose lease has expired. A box that fails a health check while its lease was renewed recently is left alone rather than replaced out from under someone.
#Snapshots
The box's home directory is tarred, less what rebuilds itself (installed dependencies and download caches), and written to S3 as one immutable object per snapshot, under the app's prefix in the workspace's region. The newest committed snapshot for a person is what their next box in that app restores.
Writes are two-phase from the box's side: begin, upload, commit. A half-uploaded object never becomes current. Both phases run the same fence: a box may write until a newer box for the same person has committed. That is what stops a box the platform has already replaced from overwriting its successor's work with stale state. Snapshots are keyed to the person's session, never to a branch, because git lets a branch move for reasons that have nothing to do with whose workspace this is.
#The Sandbox Proxy
The sandbox proxy role is the only public path to a box. It runs in the trusted VPC, reaches boxes over the peering on the dev-box port, and serves two origins from one deployment. The split is load-bearing.
| Origin | Access | Carries |
|---|---|---|
| A per-session preview host | Public | The app's preview and hot reload |
| The sandbox control host | Authenticated, per session | Control channel, language server, logs, agent state, dev-database management |
The box itself serves all of it on one port with a permissive CORS policy. On a single origin, code running in a person's own preview could read that box's logs and usage. Two origins is what closes that, and it is why the preview can stay public: there is nothing on that origin worth reaching. Control paths are an allow-list, so a route the box grows is unreachable from the preview origin until it is deliberately added.
The preview apex is a separate registrable domain from the app apex, so unreleased code never shares a cookie scope with deployed apps. The preview host names a session, not an app: an app has one box per person, and the box behind a session changes whenever that box is replaced. The editor re-points from the session payload.
The proxy is stateless. Routing is a session-row lookup: any replica can serve any box, with no sticky routing needed. It is its own role because an editor holds hour-long WebSockets that must not ride the API tier's rollout cadence.
A Cloudflare Worker owns the preview apex, terminates TLS with Universal SSL, and forwards to the sandbox proxy, carrying the browser's hostname out of band. The bare apex is the control host: the same Worker forwards it to the sandbox proxy under the proxy's own host, so the hours-long control sockets ride Cloudflare too. The box pings them every 30 seconds, and the editor reconnects when an edge restart drops one.
The control host sits on the preview apex rather than the editor's own domain because its responses are relayed from the box, which runs agent-authored code. On the editor's domain, a compromised box could set cookies the editor's session reads. Sharing a site with the previews costs nothing, since the control routes authenticate by bearer token or socket subprotocol and never read a cookie.
#The Tunnel
Every box runs a tunnel, a process beside the control server that holds the person's dev session. The platform routes that person's dev requests to a queue the tunnel drains, so method invocations from the preview run from the box's source against their dev database and the same SDK. The queue lives in Valkey, keyed by the dev release, so it survives the box. Valkey is encrypted at rest and requires TLS on every connection. It admits one user, the platform's, which signs in with short-lived IAM tokens, and unauthenticated connections are refused. The tunnel only ever runs in a box.
The dev box is never the source of truth for what ships. Publishing is a git push, and the method compiler re-resolves dependencies in a worker-derived image at publish. A box's installed dependencies ship nowhere.
#Keeping Boots Fast
The dev-box image is large, and pulling it onto a cold node is the slowest part of a boot. A low-priority balloon pod on the dev island holds the image warm on every node and reserves a box-shaped hole; when a real box needs the space, the balloon is evicted and the box starts on a node that already has the image. Bootstrap log lines from the box stream to its owner's editor over the platform's event bus while it starts, so the person watching sees the clone and install progress rather than a spinner.
#When a Workspace Ends
A person's dev workspace in an app (their dev release, its dev databases, their home snapshots and their build-usage ledger) lasts as long as they work in the app. It is retired when they no longer do: they leave or are removed from the workspace that owns the app, their account is deleted, or 30 days pass without a box of theirs in the app. A sweep every 10 minutes deletes the data, keeping only the release row that the request log and metrics join on. Removing a member also deactivates every API key assigned to them in that workspace.
If they come back, their next session clones a fresh dev release from live, and their box clones the repository instead of restoring a home.
``` Figure 08, "Dev Boxes": the kata_dev island, read as the inverse of Job Runners. Where nothing may reach into a job runner, a person reaches into a dev box and lives there, so the plate is the inbound path and the isolation around it. From the left, a browser hits two origins: a public preview host and an authenticated per-session control host. Both go through the same Cloudflare Worker, which owns the preview apex and terminates TLS: the preview host carries the app's preview and hot reload, and the bare apex carries the control channel, language server, logs and dev-database management. Both land on the sandbox proxy in the trusted VPC, which is stateless and serves both origins from one deployment, resolving a session row to a pod address. The proxy crosses the VPC trust boundary to the box on the dev-box port, the one crimson crossing on the plate and one of the three the trust-boundary chapter enumerates. Two origins is the security crux: on a single origin, code in a person's own preview could read that box's logs and usage. The dev box is the hero, a leased Kata microVM on the kata_dev island, serving the preview, control channel, language server, and hot-reload relay on one port, holding the person's working copy and a dev database cloned from live, with no public ingress and egress to the public internet only. Inside it, the tunnel long-polls the dev queue through the HTTP role. From the box, a grey dashed egress fan is the only path out: S3 for workspace snapshots (two-phase and fenced) and the callback origin for agent calls and hook endpoints. Two clocks sit beside the box: the 12-hour pod deadline owned by the orchestrator and the 30-minute lease owned by the platform, with renewal arrows from the editor keepalive (tab visible) and from each agent call. Beside Job Runners the crimson tells the isolation story at a glance: absent where nothing may enter, present exactly once where a person may.