Release Sandboxes

A deployed app's methods run in a release sandbox: a Kata microVM on the kata_apps island, assigned to one release, kept warm while the app is in use, and replaced when it is not. This chapter covers the lifecycle of that sandbox, the warm pool it comes from, what is inside it, and how it talks to the platform.

---

#Persistent, Not Per-Invocation

A release sandbox is not created per request. When a method is first invoked for a release, the platform claims a warm sandbox from the pool, configures it for that release, and records the assignment. Subsequent invocations for the same release go to the same sandbox over a persistent WebSocket connection. The sandbox stays alive as long as it is being used.

The pod owns its own death. At creation, the platform injects its timings as environment variables from one configuration file. The worker reads them and hardcodes nothing.

Sandboxes come in two roles. An interactive sandbox serves requests where a user is waiting, and it is reused across invocations. A disposable sandbox runs one execution and exits on its own. Cron and email triggers use these, so a background run never keeps a shared pod alive after the work is done. A disposable sandbox is never reused for a normal request.

---

#The Warm Pool

Every release sandbox comes from a warm pool: pods booted ahead of demand, labeled warm, waiting to be claimed. A claim turns a warm pod into this release's pod in tens of milliseconds, not the seconds a cold boot takes.

Global, not per replica. The orchestrator runs as several replicas. The pool is one pool across all of them. Which warm pod a caller receives is decided by an atomic pop in a Redis registry. The pool label on the pod then flips to claimed, and that flip is the durable record. The registry itself is an index, rebuildable from the pods, rather than a second source of truth.

Two tiers. A reserved tier is claimable only by interactive work, where a person is waiting. A shared tier is claimable by anyone, including background work. The tier is stamped on the pod at birth, so the claim enforces the partition instead of relying on callers to respect it.

One leader sizes, every replica admits. The control plane observes demand and decides how many pods should exist. It runs on exactly one replica, chosen by leadership over a Valkey lease. The data plane (the atomic claim and the waiter queue) runs on every replica. This is the standard Kubernetes controller shape: one leader-elected reconciler, everything else stateless.

The sizing is textbook queueing. The controller measures arrival rate and boot time, holds the in-flight quantity those imply plus square-root staffing headroom, adds stock for the largest burst it has recently observed, and adds anything currently queued. The target is the maximum of recent wants over a stabilization window, so scale-down happens by samples expiring rather than by a decay constant. Every term is a pure function of declared inputs, with no clock and no I/O in the decision path. That is what lets the controller's scenarios run deterministically in a regression harness.

Admission. When no warm pod is available, an interactive caller waits, within a bounded budget, for a fill. If the pool cannot honor that wait, the caller gets a clear error instead of being left hanging. Creates are paced per pass to stay inside the Kubernetes API server's fairness limits, and a rate-limit response from the API server pauses fills with jitter so replicas do not resume in lockstep.

---

#What Is Inside

The worker image is a pure runtime: a pinned Node.js, the platform SDK, and a worker process that listens on the worker port. It runs as an unprivileged user. It carries no compiler toolchain. A release's native dependencies are built once at publish and shipped in the dependency artifact.

At assignment the platform configures the sandbox with everything the release needs:

• The dependency artifact. A prebuilt node_modules tarball for the release, fetched by the pod from a short-lived presigned URL, stamped with the ABI it was built against so the worker can verify a match before extracting. See Job Runners.
• The app's own secrets. The prod values of the secrets the builder stored, decrypted by the platform and injected as environment variables. See Secrets.
• The callback origin. The one hostname the sandbox reaches back on.
• Its own sandbox id. Every execute frame names the sandbox it is for, and the worker rejects a frame addressed to a different id. Pod IPs are recycled quickly. This check is what makes a stale routing entry harmless.

Each execute frame carries the compiled handler by its immutable artifact key, the handler name, the parameters, a hook token scoped to this execution, the auth context, and the database bindings for the environment. The worker caches compiled handlers by key, so code travels only on a cold miss.

The sandbox holds only what belongs to this app. Every managed capability the app uses is a call back into the platform, authorized by the hook token: database queries go to the app database role, platform actions go to the hook endpoints, and model calls go to the model service. No provider key, no platform credential, and no other app's data is ever inside the VM.

---

#Assignment, Reuse and Invalidation

The HTTP role owns the mapping from release to sandbox in Redis. When a release is promoted, the previous release's sandboxes are stopped by app label, and the new release claims fresh ones on first use. When a secret changes, the app's sandboxes are stopped so no pod runs with stale values. Dead sandbox detection and retry live in the HTTP role: a sandbox that stops answering is dropped from the mapping and the next invocation claims another.

The worker image is pinned to a moving alias. Every pod start re-checks the digest, and the pool controller recycles warm pods running a stale image, so a push to the image rolls the warm pool without a platform deploy.