Hosting the sandbox
ClientVM needs one static deployment of the sandbox: the files in @clientvm/sandbox-host’s
dist/. It must be reachable at every instance origin https://<id>.<sandbox-domain>/. No
server-side code runs.
npm install -D @clientvm/sandbox-host
# deploy node_modules/@clientvm/sandbox-host/dist, then check it:
npx clientvm-check-sandbox 'https://{id}.myapp-sandbox.dev' --app https://myapp.example
From a checkout of this repository, pnpm --filter @clientvm/sandbox-host build writes the same
files to packages/sandbox-host/dist.
Why subdomains
The browser’s unit of isolation is the origin. ClientVM gives each instance its own, so the browser itself keeps agent code apart:
- One origin per instance (
k3x9.myapp-sandbox.dev). Each instance’s storage, service worker and windows are its own, out of reach of your app and of every other instance (ADR 0003). - One origin per preview port (
k3x9-p5173.myapp-sandbox.dev). A dev server inside an instance is served on its own origin by that origin’s service worker, so its pages are isolated too (ADR 0008). - A wildcard, because ids are made at runtime. Instances and ports come and go; the deployment must answer for any subdomain without a list.
- A separate registrable domain. Under your app’s domain (
sandbox.myapp.com) instance code would be same-site with your app: it could set cookies on.myapp.comand send same-site requests that carry your users’ credentials. A domain of its own (myapp-sandbox.dev) is cross-site. - The headers make each instance page cross-origin isolated through Document-Isolation-Policy.
That is what lets
fs.readFileSyncblock onSharedArrayBufferandAtomics.wait, and why your app needs no COOP/COEP headers (ADR 0005).
Requirements
-
A dedicated registrable domain for the sandbox, separate from your app’s (for example
myapp-sandbox.dev, notsandbox.myapp.com). Instances run hostile code, so they must not be same-site with your app. -
Wildcard DNS and TLS for
*.<sandbox-domain>, serving the same static files for every subdomain. Instance ids are DNS labels ([a-z0-9-], up to 63 chars). -
No cookies, ever, on the sandbox domain, and no authenticated endpoints. Consider adding the domain to the Public Suffix List so each instance becomes its own site to the browser.
-
Response headers on every response from instance origins:
Document-Isolation-Policy: isolate-and-require-corp Cross-Origin-Embedder-Policy: require-corp Cross-Origin-Resource-Policy: cross-origin Content-Security-Policy: frame-ancestors https://your-app.exampleframe-ancestorsshould list the app origins allowed to embed instances. The handshake is already origin-checked; this is defense in depth. -
For the service worker script (
/__clientvm/sw.js), also sendService-Worker-Allowed: /so it can control the whole instance origin. Serve it withCache-Control: no-cacheso updates are picked up. -
Keep everything under
/__clientvm/. The instance service worker forwards every other path on an instance origin to the instance’s own virtual servers, which serve its previews.
The development and preview servers (packages/sandbox-host/vite.config.ts) apply these headers
to *.localhost. Set CLIENTVM_FRAME_ANCESTORS to add the CSP header.
Check your deployment
npx clientvm-check-sandbox 'https://{id}.myapp-sandbox.dev' --app https://myapp.example
From a checkout, node scripts/check-sandbox-headers.mjs runs the same check. It requests an instance page, the service worker and a port origin on random subdomains and
fails if a requirement above is not met (it warns when frame-ancestors is missing).
Flat sandbox names
sandboxOrigin maps a label to an origin. The label is either an instance id or a port label,
<id>-p<port>. It doesn’t have to be the first DNS label of a dedicated domain. A suffix works too:
createClientVM({ sandboxOrigin: (label) => `https://${label}-cvm.example.dev` });
Instances then live at https://<id>-cvm.example.dev and previews at
https://<id>-p5173-cvm.example.dev. Everything stays one level below the zone, so a single
wildcard certificate (*.example.dev) and one wildcard DNS record cover every origin. The
project’s own demo uses this scheme on Cloudflare (deploy/sandbox-worker).
A flat scheme only works under a domain that is itself dedicated to the sandbox, or one with no cookies and no authenticated endpoints anywhere on it. Every origin it creates is same-site with the rest of that domain (see security.md).
In your app
import { createClientVM } from '@clientvm/clientvm';
const vm = createClientVM({ sandboxOrigin: (id) => `https://${id}.myapp-sandbox.dev` });
const instance = await vm.createInstance({ fs: { from: { 'index.js': "console.log('hi')" } } });
Your app needs no special headers. If your app already uses COOP/COEP, instances still work (fallback mode).
Previews
When a server inside an instance opens a port, instance.onPortOpen((port, url) => ...) reports
the port’s own origin, https://<id>-p<port>.<sandbox-domain>/ (ADR 0008). The same wildcard
deployment serves it: the controller embeds /__clientvm/port.html there to link that origin’s
service worker to the instance. Load the URL in an iframe to show the preview. Previews are
private: they only resolve inside the browser tab that runs the instance.
The service worker adds a module script, /__clientvm/ws-shim.js, to HTML pages on port origins:
browsers do not let service workers see WebSockets, so the shim carries same-origin (and
localhost) WebSockets to the server through the service worker. Port origins get the same
headers as instance origins; preview responses themselves carry only the app server’s headers.