Dev Boxes

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, and the alternative of developing on your own machine through the CLI.

---

#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 whole 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 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 hours-long control sockets do not ride the Worker; they answer on the control host directly.

---

#The CLI Tunnel

A person can develop on their own machine instead. The CLI opens a tunnel session: the platform routes that person's dev requests to a queue the CLI drains, so method invocations from the preview run locally against the same dev database and the same SDK. A dev environment records whether its origin is a box or a laptop; everything else about it is the same.

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 node_modules 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 the editor over the platform's event bus while it starts, so the person watching sees the clone and install progress rather than a spinner.