Every significant choice in ClientVM is recorded as an architecture decision record (ADR) in
docs/decisions/. This page summarises all of them. Follow a link for the full
context, the alternatives, the measurements and the consequences.
Principles that keep coming back
Let the browser enforce isolation. Instances and previews get origins of their own, so
the browser’s origin model, not ClientVM’s code, keeps them apart.
Run the real thing. Wherever upstream code can run unchanged (npm, pnpm, Node’s streams,
path and tests, cjs-module-lexer, WebAssembly builds of native tools), ClientVM runs it
rather than reimplementing it, and fixes the compat layer instead of patching the tool.
Download big tools on first use, and verify them. npm, git and the WebAssembly stand-ins
are fetched when first needed and checked against pinned or registry integrity hashes.
Measure before deciding. Wake mechanisms, storage and persistence were chosen from
measurements taken in Chromium, recorded in each ADR.
No runtime dependencies in core packages, except where an ADR justifies one.
Isolation and hosting
Decision
Why
ADR
One kernel per instance, on the instance’s own origin (a hidden iframe on <id>.<sandbox-domain>); the controller brokers everything between instances
Workers share their origin’s storage and channels; one shared origin would let instances reach each other around the kernel
Decisions are not relitigated silently. To change one, write a new ADR that supersedes it (as
0003 superseded the original single shared kernel), and update this page.