# ClientVM

> A dev machine for every AI agent, inside a browser tab. ClientVM runs Node.js 24, a real bash and the unmodified npm in the browser. Each agent gets isolated instances with their own filesystem, processes and network, runs npm install and npm run dev, and previews the app it built. No containers, no servers to pay for.

Free and open source (Apache-2.0) · Source: https://github.com/Reflex-Gravity/client-vm · Live demo: https://clientvm.joeldsouza.me/#demo

## Install

```sh
npm install @clientvm/clientvm @clientvm/terminal
```

## How it works

1. **Your page asks for a sandbox** (`vm.createInstance({ preset: 'vite-react-ts' })`). One call from your app. The controller on your page only passes messages, and checks every one; agent code never runs on your origin.
2. **It boots on its own origin** (`https://k3x9….sandbox-domain`). A hidden iframe on its own subdomain starts a kernel: a filesystem, a process table, terminals and network ports. The browser keeps it walled off from your app and from other sandboxes.
3. **Code runs as on Linux** (`npm install && npm run dev`). bash, node and npm each run in their own Web Worker and talk to the kernel through system calls. fs.readFileSync really blocks, and a system call round trip takes about 10 µs.
4. **The preview comes back** (`onPortOpen((port, url) => …)`). When a server listens on a port, a service worker serves it on its own origin. You show it in an iframe; it never leaves the tab.

## Features

- [Real npm and pnpm](https://clientvm.joeldsouza.me/docs/compatibility/): The unmodified npm 11 and pnpm 10, fetched and SHA-512-verified on first use. Lockfiles, lifecycle scripts, workspaces.
- [Vite with HMR](https://clientvm.joeldsouza.me/docs/decisions/0013-wasm-stand-ins-for-native-packages/): Stock Vite 6 and Vite 8 projects. esbuild, rollup, rolldown and lightningcss run as their official WebAssembly builds.
- [An interactive bash](https://clientvm.joeldsouza.me/docs/decisions/0017-pty-and-signals/): Pseudo-terminals, signals, Ctrl+C and Ctrl+Z, job control, history and Tab completion. About 60 Linux commands, diffed against bash and GNU tools.
- [Synchronous syscalls](https://github.com/Reflex-Gravity/client-vm/blob/main/docs/spike-results.md): fs.readFileSync really blocks, on SharedArrayBuffer and Atomics.wait, at about 10 µs per round trip.
- [One origin per instance](https://clientvm.joeldsouza.me/docs/security/): Each instance runs on its own subdomain, so the browser keeps agent code away from your app and from other instances.
- [Snapshots and forks](https://clientvm.joeldsouza.me/docs/interfaces/): Copy-on-write snapshots, forks into new instances, OPFS persistence, a mailbox and capability-gated networking between instances.
- [Tools for agents](https://clientvm.joeldsouza.me/docs/agent-api/): Files, exec, background processes, screenshots and a driveable preview, as LLM tool definitions.
- [Static hosting only](https://clientvm.joeldsouza.me/docs/hosting/): The sandbox is a folder of static files behind a wildcard subdomain. Nothing runs on a server.

## Quickstart

### 1. 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?

```text
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.

More: https://clientvm.joeldsouza.me/docs/hosting/#why-subdomains

```sh
# 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
```

### 2. Install the runtime in your app

The controller that runs on your page. It only passes messages to the sandbox and checks each one.

```sh
npm install @clientvm/clientvm
```

### 3. Boot an instance and show its preview

Point the controller at the sandbox from step 1, boot a ready project and start its dev server.

```ts
import { createClientVM } from '@clientvm/clientvm';

// the sandbox from step 1; {id} becomes each instance's subdomain
const vm = createClientVM({
  sandboxOrigin: (id) => `https://${id}.myapp-sandbox.dev`,
});

// a ready Vite + React + TypeScript project, node_modules included
const app = await vm.createInstance({ preset: 'vite-react-ts' });

// the dev server's port opens on its own origin, private to this tab
const preview = document.querySelector('iframe')!;
app.onPortOpen((port, url) => (preview.src = url));

await app.spawn('npm', ['run', 'dev'], { cwd: '/home/user/app' });
```

### Add-ons

#### Terminal

```ts
// npm install @clientvm/terminal @xterm/xterm
import { Terminal } from '@xterm/xterm'; // or any xterm.js-compatible emulator
import { attachShell } from '@clientvm/terminal';

const term = new Terminal();
term.open(document.querySelector('#terminal')!);

// a real bash: history, Tab completion, Ctrl+C, job control
await attachShell(term, app, { cwd: '/home/user/app' });
```

#### Agent tools

```ts
// npm install @clientvm/agent-api
import { createAgentTools } from '@clientvm/agent-api';

const tools = createAgentTools({ instance: app });

// send tools.definitions to the model as `tools`; for each tool call
// it makes, run the tool here in the browser and send the result back
for (const block of response.content) {
  if (block.type !== 'tool_use') continue;
  const result = await tools.call(block.name, block.input);
  results.push({ type: 'tool_result', tool_use_id: block.id, ...result });
}
```

## Limits

- **Chromium only.** v1 relies on Document-Isolation-Policy, OPFS and Atomics.waitAsync. Firefox and Safari are not supported yet.
- **No native addons.** node-gyp builds, sharp and prisma engines do not run. A few build tools are swapped for their WebAssembly builds; anything else fails with ERR_DLOPEN_FAILED.
- **The network is the browser’s.** Outbound fetch is subject to CORS, and there is no raw TCP or UDP. git remotes need a CORS proxy.
- **JavaScript only.** Node.js 24 and a TypeScript shell. No Python, no Go, no x86 emulation.
- **Pre-1.0.** The sandbox boundary has not had an independent security review yet. Every Node API we support is listed, with its gaps, in the compatibility matrix.

- [Compatibility matrix](https://clientvm.joeldsouza.me/docs/compatibility/)
- [Security model](https://clientvm.joeldsouza.me/docs/security/)
- [Security review](https://clientvm.joeldsouza.me/docs/security-review/)

## Integration prompt for coding agents

```text
Integrate ClientVM (https://github.com/Reflex-Gravity/client-vm) into this web app so it can run Node.js 24, bash and npm entirely in the browser.

1. Install @clientvm/clientvm, @clientvm/terminal and @clientvm/agent-api from npm.
2. ClientVM needs a static sandbox: install @clientvm/sandbox-host as a dev dependency and deploy its dist/ folder on a wildcard subdomain of a separate registrable domain (each instance and each preview port gets its own subdomain, so the browser isolates them from this app). Serve 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 <this app's origin>, plus Service-Worker-Allowed: / on /__clientvm/sw.js. Check it with npx clientvm-check-sandbox 'https://{id}.<sandbox-domain>' --app <this app's origin>. Follow https://clientvm.joeldsouza.me/docs/hosting.md.
3. Create a controller: createClientVM({ sandboxOrigin: (id) => `https://${id}.<sandbox-domain>` }). This app needs no COOP/COEP headers.
4. Create an instance with vm.createInstance({ preset: 'vite-react-ts' }) or from files, run commands with instance.exec / instance.spawn, and show previews from instance.onPortOpen((port, url) => ...) in an iframe.
5. For a terminal, pass an xterm.js Terminal to attachShell(term, instance) from @clientvm/terminal.
6. For LLM tools, createAgentTools({ instance }) from @clientvm/agent-api gives tool definitions and tools.call(name, input).

Limits: Chromium only, no native Node addons, outbound fetch is subject to CORS, no raw TCP. Check https://clientvm.joeldsouza.me/docs/compatibility.md before relying on a Node API.
```
