Design decisions

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 0003
Document-Isolation-Policy on instance pages Gives instances SharedArrayBuffer without forcing COOP/COEP on the host app, which breaks embeds and OAuth popups 0005
One origin per virtual port (<id>-p<port>.<sandbox-domain>) Dev servers emit absolute URLs that break under a path prefix, and previews should not share an origin with the kernel 0008
Presets are built once and cached on the host origin (Cache Storage) Instance origins cannot share anything; a ready Vite + React project then boots in about 0.2 s instead of a fresh install 0018

Processes and syscalls

Decision Why ADR
The kernel wakes with Atomics.waitAsync, with a postMessage doorbell as a fallback About 10 µs per round trip against 13.7 µs, and the kernel’s event loop stays free 0002
The shell runs its commands in its own worker; every command is also a standalone runtime A worker per grep in a loop would take seconds; PATH lookup still decides, as execve would 0011
Pseudo-terminals and delivered signals in the kernel, with job control Programs need isatty, raw mode, Ctrl+C reaching handlers and resize events to behave as on Linux 0017
Process events and a terminal package with no emulator dependency Host apps choose their own UI; output history is bounded because instance output is hostile 0016

Filesystem

Decision Why ADR
Memory-first filesystem with write-behind OPFS persistence An OPFS call costs 145–375 µs against ~10 µs in memory; npm install makes tens of thousands of calls 0004

Node compatibility

Decision Why ADR
Target Node.js 24 LTS (v24.11.0) The compat layer, the ported tests and the differential suites need one fixed reference 0001
Native ES modules, served by the service worker Real live bindings, cycles and top-level await, instead of an approximate ESM-to-CJS transform 0006
Node’s own cjs-module-lexer for CommonJS named exports Its heuristics are the specification; a reimplementation matched only 55% of 1,500 files 0009
Vendor readable-stream for stream Node’s most behaviour-sensitive code; a rewrite would only approximate it 0010
Vendor pako for zlib npm needs synchronous, incremental inflate, which the browser does not offer 0007
Vendor Node’s lib/path.js and the passing subset of Node’s tests path then matches Node by construction, and the test subset is a ratchet in CI 0015

Tools and packages

Decision Why ADR
npm is the unmodified release, fetched and SHA-512-verified on first use Too big to bundle into every instance; running it unpatched avoids reimplementing its resolution 0012
WebAssembly stand-ins for native toolchain packages (esbuild, rollup, rolldown, lightningcss, Tailwind’s oxide) Stock Vite projects work unchanged, using each project’s own official WebAssembly build of the same version 0013
git on isomorphic-git, fetched and verified on first use A pure-JavaScript git that reads and writes real repositories; porcelain output is diffed against real git 0014

Proposing a change

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.

Edit this page on GitHub ↗View as MarkdownUpdated