Documentation
How to host the sandbox, the public API, the tools for agents, what Node APIs work, and the reasoning behind each design decision. Internal plans and measurements stay in the repository.
Get started
- Hosting the sandboxClientVM 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>/.…
- InterfacesThe public API is declared in packages/clientvm/src/types.ts and implemented by createClientVM() in controller.ts. Changes to that file must update this page and, if they…
- Agent tool APIThe definitions and results map one-to-one onto the Messages API's tools and tool_result blocks:
Reference
- Compatibility matrixClientVM does not claim generic "Node compatibility". This page is the source of truth for what works, how it is tested, and the known gaps.
- Packages and how ClientVM worksA guide to the ten packages under packages/ and how they work together. For the decisions behind them see CLAUDE.md and decisions/; for API status see interfaces.md; for what…
- ArchitectureThe target architecture is in CLAUDE.md §4. This page records what is built and how a syscall travels today.
Security
- Security model and threat modelClientVM 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…
- Security review checklistCLAUDE.md §9 requires a security review of the sandbox boundary before any 1.0 claim. This is the checklist for that review. The threat model is in security.md. Each item says…
Design decisions
- 0001 · Target Node.js 24 LTS for the compat layer
- 0002 · Wake the kernel with Atomics.waitAsync for sync syscalls
- 0003 · One kernel per instance, on the instance's own origin
- 0004 · Memory-first VFS with write-behind OPFS persistence
- 0005 · Document-Isolation-Policy for instance pages
- 0006 · Run ES modules natively, served by the instance service worker
- 0007 · Vendor pako for zlib
- 0008 · One sub-origin per virtual port
- 0009 · Use cjs-module-lexer for CommonJS named exports
- 0010 · Vendor Node's streams (readable-stream) for `stream`
- 0011 · The shell runs its commands in-process; every command is also a runtime
- 0012 · npm is the unmodified release, fetched and verified on first use
- 0013 · WebAssembly stand-ins for native toolchain packages
- 0014 · `git` runs on isomorphic-git, fetched and verified on first use
- 0015 · Vendor Node's `lib/path.js` and the passing subset of Node's tests
- 0016 · process events and a dependency-free terminal package
- 0017 · pseudo-terminals and signal delivery
- 0018 · Presets, built once and cached on the host origin