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