Security model and threat model
ClientVM runs code written by AI agents and code from arbitrary npm packages. All of it is treated as hostile. This document must stay current. Every PR that changes a trust boundary updates it.
Assets
- Host app origin. Its cookies, storage, credentials, and DOM. The most important asset.
- Other instances. Their filesystems, processes, network ports, and mailboxes.
- The user’s browser tab. Memory, CPU, and responsiveness.
- The user’s network position. Requests sent from the user’s browser and IP.
Adversaries
- Agent-generated code running in a process, including code an attacker prompt-injected into the agent.
- Malicious or compromised npm packages (install scripts and runtime code).
- Content inside a preview iframe, such as a generated app that loads third-party scripts.
Trust boundaries
Host app + controller (trusted, app origin, never runs instance code)
║ handshake via postMessage: exact source window + origin checks; then a MessagePort.
║ The controller validates every value an instance sends. ← boundary 1
Instance iframe on <id>.<sandbox-domain> (one origin per instance) ← boundary 2 (browser origin model)
└─ kernel worker (our code, but shares the origin with hostile code)
║ SAB channel + postMessage; kernel validates every request ← boundary 3
└─ process workers (untrusted code)
└─ service worker for module loading and in-instance fetch
Port origins <id>-p<port>.<sandbox-domain> (one per open port, ADR 0008)
└─ bridge page + service worker + preview iframes running the app's own pages.
The SW only reaches its own port through a channel the controller handed the kernel.
Mitigations (planned and status)
| Mitigation | Status |
|---|---|
| Runtime executes on a separate sandbox origin, never the host app’s origin | done (2b) |
| One origin and one kernel per instance, isolating storage, BroadcastChannel and SW between instances (ADR 0003) | done (2b), e2e-tested |
| Sandbox origin serves static files only, sets no cookies, and has no authenticated endpoints | documented (hosting.md) |
| Host ↔ instance handshake checks the source window and exact origin on both sides; the controller validates all instance replies and events | done (2b) |
frame-ancestors CSP restricts who can embed instance pages |
supported (hosting config) |
Kernel decodes every syscall defensively (type-checked args, EINVAL on malformed input, ENOSYS on unknown ops) |
done (spike) |
| Process workers get no direct VFS access, only the syscall channel | done |
| Each process gets its own channel SAB, so processes cannot read each other’s syscall traffic | done |
| Capabilities for every cross-instance interaction, checked in the controller (kernels run hostile code and never see the table) | done (4a–4c) for mailbox, .internal HTTP, mounts and spawn-instance, e2e-tested. Revoking a mount capability stops its sync |
The preview agent accepts a connection only from its parent window, and the host validates everything it sends (snapshots, console entries, screenshots). evaluate runs in the preview’s port origin, which already runs the instance’s code. Agent output is untrusted data for an LLM (prompt-injection risk), not instructions |
done (4d) |
Requests a kernel makes of the controller (mailboxSend, netFetch) are validated and run with that instance’s capabilities only; mailbox messages are re-serialized as JSON so instances never share objects |
done (4a/4b) |
Resource limits per instance: maxProcesses, quotaBytes/maxInodes (ENOSPC), 1024 open files per process, maxCpuMs (a process that runs without yielding is killed with SIGXCPU), 8 MiB of unread output per stream in the controller, Instance.exec timeoutMs |
done (2c, 5c), e2e-tested. maxMemoryMB is not enforced (open-questions.md) |
The service worker never routes /__clientvm/* (ClientVM’s own page, workers and SW script) to instance servers, so instance code cannot shadow them |
done (2d), e2e-tested |
| The service worker accepts a kernel link only from the instance page | done (2d) |
| Preview pages run on a per-port origin, not the kernel’s: app code cannot touch the kernel’s OPFS store, the instance page, or other ports’ storage. A port origin’s link serves only its own port, never the module routes | done (3d), e2e-tested |
Instance ids cannot end in -p<digits>, so an instance never shares an origin with another instance’s port |
done (3d) |
| Fuzzing of codec, channel, VFS, resolver, shell parser | done (5b): seeded tests for the protocol codec, tar reader, path, CommonJS resolver, VFS operations and shell parser. Runs in CI with fixed seeds; FUZZ_SEED/FUZZ_ITERATIONS for longer runs |
Threads (worker_threads, child_process.fork) are kernel processes: same syscall checks, process limit and CPU watchdog. Parent and child share only a MessagePort the kernel created |
done (5a) |
Pseudo-terminals (ADR 0017): terminal output is instance output like any other and goes through the same 8 MiB handle buffer and onProcess bounds; attachShell sanitizes it as the activity view does. Window sizes are validated (1 to 10000) in the controller and the kernel. Signals are delivered within the instance only, and a process that does not act on one within 1 s is terminated, so a handler cannot make a process unkillable (SIGKILL stays immediate) |
done (T2), e2e-tested |
Process output shown in the host page (@clientvm/terminal, ADR 0016): the controller keeps at most 100 processes and 256 KiB of output each for onProcess replay; attachActivityView strips string escape sequences (OSC 52 clipboard writes, OSC 8 links, DCS/APC) except titles and draws commands without control characters; feed output is meant to be rendered as text, never HTML |
done (T1, T3), unit-tested. Views draw at most 64 Ki characters a frame and skip the oldest lines beyond a 1 Mi-character backlog; the only links in a view are ClientVM’s own, to the instance’s open ports. Persisted scrollback (sessionStorage) is the sanitized text |
Agent-supplied regexes (grep, sed, find -regex, [[ =~ ]]) run on the JS regex engine and can backtrack catastrophically. They run in the instance’s own worker, so a bad pattern only stalls that process; Instance.exec timeoutMs stops it |
documented |
What a compromised instance can do
Code in an instance can do anything its own origin can do. It can rewrite its own kernel’s memory (the kernel shares the agent cluster), read and write its own filesystem and OPFS, register a service worker for its own origin, and send arbitrary messages to the controller. It cannot reach other instances’ storage or channels, or the host app’s origin. Everything it sends the controller is validated before use. A hostile instance can lie about its own files and process output, but it cannot affect the controller or other instances.
Persisted data
A persistent instance’s store lives in its own origin’s OPFS (clientvm/v1/). Processes in that
instance can read and tamper with it, which only affects that instance. Loading validates the
structure and fails closed on corruption. Storage partitioning keys it by the host app’s
top-level site.
Preset images (ADR 0018) are the one thing ClientVM keeps on the host origin, in Cache
Storage (clientvm-presets) or a host-supplied presetStore. Only the controller writes them,
from a builder instance that runs the pinned template and setup and never agent code, so an
instance cannot plant files in another’s starting image. Images hold public packages only and are
validated at boot like any image; a stored image that fails its framing check is dropped and
rebuilt.
Known risks and open issues
- Spectre / high-resolution timers. Cross-origin isolation re-enables SAB and precise timers. COEP keeps cross-origin resources that haven’t opted in out of the process, but code in a process can still time other code in the same agent cluster. Per-instance origins limit what shares that cluster. Verify how Chromium assigns site isolation and processes for subdomains of one registrable domain: same-site subdomains may share a renderer process.
- Embedding by third parties. Anyone can embed an instance page. They cannot connect to it
unless they are its parent at the claimed origin. Storage partitioning keys an embedded
instance’s OPFS by the top-level site, so other sites cannot read your users’ persisted
instances.
frame-ancestorsadds defense in depth. - Same-site subdomains.
<id>.<sandbox-domain>origins are same-site with each other. Cookies withDomain=<sandbox-domain>would be shared, so the sandbox domain must never set cookies. Consider listing the sandbox domain on the Public Suffix List so each instance is its own site. - Service worker hijack. Preview documents and processes share the instance origin with the SW, so they can register a replacement SW or read the instance’s storage. The blast radius is that one instance’s previews and data, which that code already controls. A replacement SW cannot affect other instances (different origins) or the host app. Preview documents should not be treated as trustworthy by the host app; only read them through the controller.
- Kernel DoS.
maxCpuMsstops a process that spins without yielding, output caps bound what the controller buffers, andquotaBytesbounds the filesystem. Still open: a process that yields regularly can run forever (usetimeoutMsorkill), memory is not capped (maxMemoryMB), and the defaults are unlimited: integrators must set limits for untrusted use. evalin process workers. The node runtime uses indirectevalby design. The sandbox boundary is the worker and origin, not the JS realm.- Outbound network. Process code can
fetchany CORS-enabled endpoint from the user’s browser. Document this for integrators. A capability gate on outbound fetch is an open question. - WebAssembly stand-ins (ADR 0013). esbuild-wasm and @rollup/wasm-node are fetched on first
use and checked against the integrity the registry publishes for them. That is the same trust
npm installplaces in the registry, not a pin in ClientVM. They run with the instance’s authority like any package code. - pnpm and git. pnpm 10.34.7 and isomorphic-git 1.44.3 are pinned by SHA-512 like npm
(ADRs 0012, 0014), so a compromised registry cannot swap them.
GIT_TOKENandGIT_CORS_PROXYare visible to everything in the instance; a CORS proxy sees every request and credential sent through it. - npm supply chain. npm itself is pinned by SHA-512 (ADR 0012), so a compromised registry
or mirror cannot swap the npm CLI. Packages that npm installs are checked against their lockfile
integrity, as npm normally does, but their code and lifecycle scripts are untrusted and run with
the instance’s full authority. Running
npm install --ignore-scriptsreduces what runs during install, not what runs atrequiretime. - The project’s own demo sandbox shares a registrable domain. The live demo on
https://clientvm.joeldsouza.me runs instances on
<label>-cvm.joeldsouza.me(deploy/sandbox-worker). That is the same site as the landing page and everything else onjoeldsouza.me, against requirement 1 of hosting.md. Instance code there can set cookies for.joeldsouza.me(cookie tossing) and sends same-site requests with anySameSite=Laxcookies the domain holds. This is acceptable only because nothing onjoeldsouza.meuses cookies, sessions or logins. If that changes, the demo sandbox must move to a dedicated domain first. Integrators must still use a separate registrable domain.
Review status
Before any 1.0 claim (CLAUDE.md §9) the sandbox boundary needs an independent review. security-review.md is the checklist for it, with what has been verified so far and how.
Not in scope
The host app’s own security, and anything the user explicitly deploys outside ClientVM.