ADR 0008: One sub-origin per virtual port
- Status: accepted (2026-10-21), implemented in Phase 3d. Processes inside the instance still
reach ports through
/__port/<n>/ on the instance origin (that is where their localhost
requests go).
- Context: Dev servers emit absolute URLs (
/assets/x.js, /@vite/client). Under a
/__port/<n>/ prefix those resolve against the wrong server. Previews served from the kernel’s
own origin also share storage with the kernel and processes.
- Decision: Each open port gets its own origin,
<id>-p<port>.<sandbox-domain>. The
controller links that origin’s service worker to the instance kernel by transferring a
MessagePort through a small bridge page on the port origin.
- Consequences: Every port behaves like a real origin, and preview code no longer shares an
origin with the kernel. The same wildcard DNS works, but instance ids must leave room for the
-p<port> suffix within a 63-character DNS label: ids are limited to 56 characters and may not
end in -p<digits>.
- Implementation: the controller embeds
/__clientvm/port.html on the port origin. The bridge
registers the same service worker, says hello, receives a MessagePort whose other end the
controller handed to the kernel (linkPort), passes it to its service worker, and acknowledges.
Only then is the URL reported. A service worker that restarts or updates asks the bridge, which
asks the controller for a fresh channel. On a port origin the service worker forwards every
path except /__clientvm/* to the port, injects /__clientvm/ws-shim.js into HTML documents,
and tunnels the shim’s WebSockets to the server’s upgrade handler.
Edit this page on GitHub ↗Markdown