ADR 0003: One kernel per instance, on the instance’s own origin
- Status: accepted (2026-10-21). This supersedes the original design of a single kernel on one
shared sandbox origin.
- Context: Workers share their origin’s storage (OPFS, IndexedDB, Cache Storage),
BroadcastChannel, and service worker. A SharedArrayBuffer cannot be posted to a different
origin. If one kernel on one sandbox origin ran every instance’s processes, hostile code in
instance A could read B’s persisted files and talk to B’s processes. The kernel couldn’t
prevent it, because those APIs don’t go through syscalls.
- Decision: Each instance is a hidden iframe on
<id>.<sandbox-domain>. Its page starts a
kernel worker, which starts that instance’s process workers. The controller on the host
page is the trusted broker for everything that crosses instances: creation, fork, and later
mailbox, virtual network and capabilities. The controller talks to each kernel over a
MessagePort and treats everything it receives as untrusted.
- Consequences:
- Isolation between instances is enforced by the browser’s origin model, not our code. The
instances.spec.ts e2e suite checks it (BroadcastChannel, OPFS).
- Forks across instances copy data: an image is exported, transferred and imported. Snapshots
stay copy-on-write inside one kernel.
- Each instance pays for an iframe plus a kernel worker (about 56 ms to boot, small memory).
- Cross-instance services (Phase 4) are brokered through the controller. Revisit a dedicated
hub origin if the controller becomes a bottleneck.
Edit this page on GitHub ↗Markdown