Deploy the sandbox, once
A folder of static files, served on every subdomain of a domain of its own. Each instance and each preview gets its own subdomain, so the browser walls agent code off from your app and from every other instance.
Why a wildcard subdomain on a separate domain?
myapp.example your app: the controller, no special headers └─ k3x9.myapp-sandbox.dev instance: its own kernel, files, processes └─ k3x9-p5173.myapp-sandbox.dev preview of the dev server on port 5173
- The browser isolates origins: storage, service workers and windows. One origin per instance keeps its code out of your app and out of the other instances.
- Previews get an origin per port, served by that origin’s service worker, so an app’s pages are isolated too.
- Instance ids and ports are made at runtime, so the deployment must answer for any subdomain: a wildcard, not a list.
- Under your own domain (sandbox.myapp.com) instance code would be same-site with your app, and could set cookies on .myapp.com. A separate domain keeps it cross-site.
- The headers make every instance page cross-origin isolated (Document-Isolation-Policy). That is what lets fs.readFileSync really block, and why your app needs no COOP/COEP.
# static files, no server code
npm install -D @clientvm/sandbox-host
# deploy node_modules/@clientvm/sandbox-host/dist to *.myapp-sandbox.dev,
# with these headers on every response:
# 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://myapp.example
# (and Service-Worker-Allowed: / on /__clientvm/sw.js)
# then check the deployment
npx clientvm-check-sandbox 'https://{id}.myapp-sandbox.dev' --app https://myapp.example