sandboxedjs 0.2.8 → 0.2.10

package/README.md

@@ -1,12 +1,25 @@
-# sandboxedjs
+<div align="center">
 
-A Linux-like container that runs entirely inside a Node.js process. No Docker, no VM, no native
-modules — a virtual filesystem, a POSIX shell, 154 Unix programs, and both Node.js and Python
-runtimes, all in-process.
+<img src="/assets/logo.png" alt="SandboxedJS" width="140" />
 
-The Node.js runtime is its own: a module engine that loads both CommonJS and ES modules, an
-in-memory volume, an npm-registry installer and a virtual HTTP stack, with no native modules and
-no dependency on the host's `node_modules`.
+# SandboxedJS
+
+**A Linux-like operating system of its own — written in JavaScript, running inside a browser tab or a Node process.**
+
+Not a Linux kernel, not a VM, not Docker, not WebContainers. Its own filesystem, shell, process
+table, package installer and network stack, all in memory, booting in about 100 ms.
+
+[![npm](https://img.shields.io/npm/v/sandboxedjs?color=cb0000&label=npm)](https://www.npmjs.com/package/sandboxedjs)
+[![license](https://img.shields.io/badge/license-MIT-black)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A518.17-5fa04e)](https://nodejs.org)
+[![runs in](https://img.shields.io/badge/runs%20in-browser%20%C2%B7%20node-4c8bf5)](#running-in-a-browser)
+![no docker](https://img.shields.io/badge/docker-not%20required-2496ed)
+
+`shell` · `160 commands` · `Node 22` · `CPython 3.13` · `pip` · `npm` · `WASI` · `FFmpeg` · `previews`
+
+</div>
+
+---
 
 ```ts
 import { createContainer } from "sandboxedjs";
@@ -22,104 +35,14 @@ await box.exec("python3 -c 'print(2**64)'"); // → 18446744073709551616
 box.dispose();
 ```
 
-## Python packages with compiled extensions
-
-`pip install` works for packages with C, Cython, Rust or Meson extensions. A
-wheel built for this runtime is used when one exists; otherwise one is built
-from source, from a recipe generated out of what PyPI and the package already
-state.
-
-```js
-configurePython({ buildFromSource: true });                          // build here (Node)
-configurePython({ buildFromSource: "http://localhost:4180/build" }); // ask a builder
-```
-
-Browsers have no compiler, so they ask a machine that does:
-
-```bash
-npx sandboxedjs-build-wheels 4180
-```
-
-See `docs/python/build-on-miss.md`, and `docs/python/compatibility.md` for what
-has been built and tested.
-
-## Outbound requests from a browser
-
-A page may read a response only from a host that sends CORS headers back, and
-most APIs send none — an `Authorization` header alone forces a preflight that
-plenty of them answer with 405. A container whose guest calls a real API
-therefore works under Node and fails in a browser, for a reason that belongs to
-the page rather than to anything in the container.
-
-Give it somewhere to send those requests instead. Add that somewhere to the
-project that is already being deployed, and the container finds it by itself:
-
-```bash
-npx sandboxedjs-egress init --allow api.openai.com,ollama.com
-```
-
-That writes one file at the path the host platform serves — Cloudflare Pages,
-Vercel and Netlify are detected, `--target` names one — and nothing else
-changes. A container in a page probes its own origin for the proxy before it
-gives up, so no project passes `proxy` and none of them has to be told twice.
-
-In development the same proxy runs as a process, on the port the probe checks:
-
-```bash
-npx sandboxedjs-egress
-```
-
-In an app that already has a server, mount the handler on the well-known path.
-Before any body parser: it reads the request stream itself.
-
-```ts
-import { egressNodeHandler, EGRESS_PATH } from "sandboxedjs/egress";
-app.use(EGRESS_PATH, egressNodeHandler({ allow: ["ollama.com"] }));
-```
-
-A static host takes the `Request` form — which is what `init` writes:
-
-```ts
-// functions/__sandboxedjs__/egress.ts, on Cloudflare Pages
-import { handleEgressRequest } from "sandboxedjs/egress";
-export const onRequest = ({ request }) => handleEgressRequest(request, { allow: ["ollama.com"] });
-```
-
-`network: { proxy }` still names one explicitly — a proxy somewhere else, or
-one that discovery should not be trusted to find — and it is never overridden.
-`sandboxedjs-serve` mounts the proxy itself, so an app served by it needs none
-of this.
-
-Every exit honours it — `curl`, `wget`, a guest's own `fetch`, and Python's
-sockets — so it means the same thing whatever the project is written in.
-Loopback stays inside the container, and the container's outbound policy still
-applies before anything is handed over: a proxy widens what a *page* can reach,
-not what the container may.
-
-Anything that can reach the proxy can make requests through it carrying
-whatever credentials the guest holds, so keep `--allow` set, keep it on
-loopback in development, and put it behind your own authentication in
-production.
-
-## Servers inside the container
-
-A project split into a frontend and a backend calls `http://localhost:8000/api`
-from the frontend. That address is true inside the container and is what the
-project uses everywhere else, so it is left exactly as written: a script in
-each previewed page rewrites loopback addresses to the preview's own origin,
-and the service worker routes them by the port in the path.
-
-That works between pages of the preview, and from another tab of the same
-browser while the page holding the container is open. It does not work from
-outside that browser — Postman, curl, another machine — because the container
-is the tab. There is no server anywhere to reach.
+The same line boots in Node and in a page. Nothing is compiled, nothing is downloaded, nothing
+touches your disk.
 
 ## Why
 
-Sometimes you need to run untrusted or generated code, give an AI agent a shell, build a
-browser-based IDE backend, or teach Unix — and spinning up a real container is too heavy, too
-slow, or unavailable (serverless, CI, the browser). `sandboxedjs` boots in about 100 ms, costs
-nothing but memory, and never touches your real filesystem.
+Run untrusted or AI-generated code. Give an agent a real shell. Build a browser IDE that actually
+installs packages and starts servers. Teach Unix without handing out VMs. A real container is too
+heavy, too slow, or simply unavailable — in a browser tab, in a serverless function, in CI.
 
 ## Install
 
@@ -127,622 +50,154 @@ nothing but memory, and never touches your real filesystem.
 npm install sandboxedjs
 ```
 
-Node 18.17+. Everything is pure JavaScript and WebAssembly — no compilation step.
-
-## Deep Agents
-
-`SandboxedJsBackend` lets [LangChain Deep Agents](https://github.com/langchain-ai/deepagents)
-use a `sandboxedjs` container as its execution and filesystem sandbox. Install the two packages
-in the host application (plus the LangChain model adapter for your provider):
-
-```bash
-npm install sandboxedjs deepagents
-```
-
-Create a container, pass its backend to `createDeepAgent`, and dispose the container when the run
-is finished:
-
-```ts
-import { createContainer } from "sandboxedjs";
-import { SandboxedJsBackend, installSandboxSkills } from "sandboxedjs/agent";
-import { createDeepAgent } from "deepagents";
-
-const box = await createContainer({
-  cwd: "/app",
-  network: { allowOutbound: true }, // required for npm installs or other downloads
-});
-
-await installSandboxSkills(box); // optional: installs the bundled sandbox workflow skills
-
-// `model` is any chat model supported by Deep Agents, configured by your application.
-const agent = createDeepAgent({
-  model,
-  backend: new SandboxedJsBackend(box, { cwd: "/app" }),
-});
-
-const result = await agent.invoke({
-  messages: [{ role: "user", content: "Create and test a small Node.js service in /app." }],
-});
-
-box.dispose();
-```
-
-The adapter mirrors `deepagents@1.13.2`'s `SandboxBackendProtocolV2` and provides shell execution plus
-`ls`, `read`, `readRaw`, `write`, `edit`, `grep`, `glob`, `delete`, file upload, and file download
-operations. Paths passed to filesystem tools must be absolute. `deepagents` is intentionally not a
-runtime dependency of `sandboxedjs`; applications that use this integration install and configure
-it alongside their model provider.
+Node 18.17+. Pure JavaScript and WebAssembly — no build step, no native modules.
 
 ## What's inside
 
 | | |
 |---|---|
-| **Filesystem** | Full FHS tree (`/etc`, `/usr`, `/var`, `/home`, …), permissions, ownership, symlinks, hard links, `umask`, sticky bits |
-| **Shell** | POSIX `sh` (54 builtins) — pipelines, redirection, here-docs, globbing, brace/parameter/arithmetic/command expansion, functions, `if`/`for`/`while`/`case`/`select`, job control, traps, arrays, `[[ ]]`, `(( ))` |
-| **Coreutils** | 154 programs — `ls cat cp mv rm mkdir grep sed awk find head tail sort uniq wc cut tr tee xargs chmod chown ln du df ps tar gzip base64 sha256sum diff curl wget` and the rest — plus 54 shell builtins |
-| **Node.js** | Its own module engine — `require` *and* `import`, live bindings, `exports` maps, top-level `await`, npm packages, `http`, `fs`, streams, `child_process` |
-| **Python** | Source-built CPython 3.13/WASM on the *same* filesystem, with the real standard library |
-| **WebAssembly** | A WASI (`preview1`) host — run any `wasm32-wasi` binary from clang, Rust, Zig or TinyGo as an ordinary process, on the same filesystem |
-| **FFmpeg** | `ffmpeg` and `ffprobe` (FFmpeg 5.1) reading and writing container files directly — [optional install](#video-and-audio) |
-| **`/proc`** | Live and synthesised — `ps`, `top`, `free` and `uptime` all read the same source |
-| **Networking** | Virtual interfaces, `/etc/hosts` resolution, in-container HTTP servers, an optional bridge to a real host port |
-| **Users** | Real `/etc/passwd` and `/etc/group`; `useradd`, `su`, `sudo`, and permission checks that deny for real — for the shell and Python, [but not Node](#the-in-container-user-model-does-not-constrain-nodejs) |
-
-Everything shares one filesystem. A file written by `echo` is readable by `require('fs')` in a
-Node script and by `open()` in Python, in either direction.
-
-## Guide
-
-### Booting
-
-```ts
-const box = await createContainer({
-  files: { "/app/index.js": "…" },   // seed the filesystem
-  cwd: "/app",                        // default working directory
-  hostname: "sandbox",
-  user: "root",                       // or a name → uid 1000 with sudo
-  env: { NODE_ENV: "production" },
-  memory: 2 * 1024 ** 3,              // what `free` and /proc/meminfo report
-  cpus: 4,                            // what `nproc` reports
-  network: { allowOutbound: false },  // outbound is off by default
-  timeoutMs: 30_000,                  // default limit for exec()
-});
-```
+| **Filesystem** | A full FHS tree in memory (`/etc`, `/usr`, `/var`, `/home`), permissions, ownership, symlinks, hard links, `umask` |
+| **Shell** | POSIX `sh` — pipes, redirection, here-docs, globbing, functions, loops, job control, traps, `[[ ]]`, `(( ))` |
+| **Commands** | 160 programs: `ls cat grep sed awk find sort tar gzip curl wget diff sha256sum ps top` … |
+| **Node.js** | Its own runtime reporting v22.12.0 — CommonJS *and* ESM, `http`, `fs`, streams, `child_process`, npm and npx |
+| **Python** | Source-built CPython 3.13 (WASM) on the same filesystem, with `pip` |
+| **WebAssembly** | A WASI preview1 host: any `wasm32-wasi` binary runs as an ordinary process |
+| **FFmpeg** | `ffmpeg` / `ffprobe` 5.1 over container files — [optional install](#video-and-audio) |
+| **Network** | In-container HTTP servers, loopback, live previews, and a proxy for real outbound calls |
 
-`files` keys may be absolute or relative to `cwd`; parent directories are created for you, and
-values may be strings or `Uint8Array`s. That is the quickest way to drop a whole project in.
+One filesystem underneath all of it: a file written by `echo` is read by `require('fs')` and by
+Python's `open()`, in any direction.
 
-### Running commands
+## Quick tour
 
 ```ts
-const { stdout, stderr, exitCode, output } = await box.exec("grep -c . /etc/passwd");
+const box = await createContainer({ cwd: "/app", network: { allowOutbound: true } });
 
-await box.exec("cat", { stdin: "piped in" });
-await box.exec("npm test", { cwd: "/app", onStdout: (t) => process.stdout.write(t) });
-await box.exec("whoami", { user: "alice" });
-await box.exec("sleep 60", { timeoutMs: 1000 }); // → { timedOut: true }
+await box.exec("npm install express", { cwd: "/app", timeoutMs: 300_000 });
+box.spawn("node server.js", { cwd: "/app" });
+await box.waitForPort(3000);
 
-await box.run(["echo", "no shell parsing here"]);
+const res = await box.request(3000, { path: "/api" });   // talk to it from your code
+console.log(res.status, res.json());
 ```
 
-`exec` is stateless, like `docker exec`. For a shell that remembers things, use a session:
+A stateful shell, when `exec` alone is too forgetful:
 
 ```ts
 const session = box.session();
 await session.run("cd /app");
 await session.run("export TOKEN=abc");
-await session.run("echo $TOKEN in $(pwd)"); // → abc in /app
+await session.run("echo $TOKEN in $(pwd)");   // → abc in /app
 ```
 
-### Long-running processes
-
-A job put in the background with `&` keeps running after the command that started it returns,
-even from a stateless `exec`, and stops with `kill %N` in a session or when the container is
-disposed:
-
-```ts
-await box.exec("node server.js > /tmp/server.log 2>&1 &", { cwd: "/app" });
-await box.waitForPort(3000);
-```
-
-To hold the process yourself, spawn it:
-
-```ts
-const proc = box.spawn("node server.js", { cwd: "/app" });
-
-for (;;) {
-  const line = await proc.stdout.readLine();
-  if (line === null) break;
-  console.log("[server]", line);
-}
-
-proc.kill();
-```
-
-### Servers
-
-An HTTP server started inside the container is reachable three ways:
-
-```ts
-box.spawn("node /app/server.js");
-await box.waitForPort(3000);
-
-// 1. programmatically
-const res = await box.request(3000, { path: "/api", method: "POST", body: "{}" });
-console.log(res.status, res.json());
-
-// 2. from inside, with the usual tools
-await box.exec("curl -s localhost:3000/api");
-
-// 3. from your machine or a browser
-const bridge = await box.expose(3000);
-console.log(bridge.url); // http://127.0.0.1:54321
-await bridge.close();
-```
-
-### Showing a live preview in an IDE
-
-A container's port is virtual. Its printed `http://localhost:5173` is not automatically
-reachable from your browser. Render a whole site in an iframe using the bridge for your host:
-
-| Container host | API | Browser-facing URL |
-| --- | --- | --- |
-| Browser only | `createPreview(box)` | A service-worker URL from `preview.urlFor(port)` |
-| Node.js | `box.expose(port)` | A real loopback HTTP URL from `bridge.url` |
-
-Browser-only example, after starting a server in `box`:
-
-```ts
-import { createPreview } from 'sandboxedjs';
-if (!(await box.waitForPort(5173, { timeoutMs: 60_000 }))) {
-  throw new Error('Server did not start; inspect its logs');
-}
-const preview = await createPreview(box);
-if (!preview) throw new Error('Secure context and service-worker support required');
-iframe.src = preview.urlFor(5173);
-// On teardown: remove the iframe, await preview.dispose(), then dispose the container.
-```
-
-The service worker routes that iframe's HTML, scripts, styles and API requests into the
-container without rewriting the site's asset paths. Keep its owner page alive.
-
-**Trust and scope:** this browser preview runs on the host page's origin. It is for trusted
-code, not a security boundary for arbitrary projects. Both preview bridges handle HTTP;
-WebSocket HMR is not implemented, so reload the iframe after changes.
-
-For complete browser and Node examples, IDE lifecycle/port selection, hosting requirements,
-single-response rendering and troubleshooting, see [Server preview integration](docs/server-previews.md).
-For the startup bug investigation and validation, see [Runtime lifecycle fixes](docs/runtime-lifecycle-fixes.md).
-
-### npm and npx
-
-> **Anything that downloads needs `network: { allowOutbound: true }`.**
-> Outbound access is off by default, so a fresh container cannot reach
-> registry.npmjs.org. `npm install` and `npx <not-yet-installed>` will fail
-> until you turn it on. This is the single most common surprise — if a package
-> command is failing, check this first.
-
-```ts
-const box = await createContainer({
-  cwd: "/app",
-  network: { allowOutbound: true }, // ← without this, npm/npx cannot install
-  files: {
-    "/app/package.json": JSON.stringify({
-      name: "api",
-      scripts: { start: "node server.js" },
-      dependencies: { express: "^4.19.2" },
-    }),
-    "/app/server.js": `
-      const express = require('express');
-      const app = express();
-      app.get('/', (req, res) => res.json({ ok: true }));
-      app.listen(3000);
-    `,
-  },
-});
-
-await box.exec("npm install", { cwd: "/app", timeoutMs: 300_000 });
-box.spawn("npm start", { cwd: "/app" });
-await box.waitForPort(3000);
-```
-
-`yarn` and `pnpm` map onto the same installer. `apt`/`apt-get` reports the built-in package set
-rather than pretending to download Debian archives.
-
-#### npx
-
-`npx` works the way you expect: it runs a local binary if there is one, and otherwise installs
-the package first.
-
-```ts
-const box = await createContainer({ cwd: "/app", network: { allowOutbound: true } });
-
-await box.exec("npx cowsay hello");         // installs cowsay, then runs it
-await box.exec("npx cowsay hello");         // second time: instant, already installed
-await box.exec("npx sharjeelbaig");         // any package with a bin works
-await box.exec("npx -p typescript tsc -v"); // package name ≠ command name
-await box.exec("npx prettier@3.3.3 --check ."); // pin a version
-await box.exec("npx --no-install eslint");  // fail instead of installing
-```
-
-Install progress goes to stderr, so `npx cowsay moo | head -3` pipes cleanly.
-
-Without `allowOutbound`, a *not-yet-installed* command fails with a message that names the real
-problem:
-
-```
-npx: could not determine executable to run: cowsay
-npx: 'cowsay' is not installed, and installing it needs network access.
-npx: Outbound network access is disabled for this container.
-npx: Enable it with createContainer({ network: { allowOutbound: true } }).
-```
-
-Commands already present — anything in `node_modules/.bin` or on `$PATH` — still run offline.
-
-### Walkthrough: Hello React, in your browser
-
-End to end — build a React app inside the container and open it in your own browser. Copy this
-into `hello-react.mjs` and run `node hello-react.mjs`.
-
-React itself comes from a CDN through an import map, so there is no bundler to configure; the
-container only has to compile JSX and serve files.
-
-```js
-import { createContainer } from "sandboxedjs";
-
-const box = await createContainer({
-  cwd: "/app",
-  network: { allowOutbound: true }, // needed to install the JSX compiler
-  files: {
-    // 1. The React component, in real JSX.
-    "/app/src/App.jsx": `
-      import { useState } from 'react';
-
-      export default function App() {
-        const [name, setName] = useState('world');
-        return (
-          <main style={{ fontFamily: 'system-ui', padding: '3rem' }}>
-            <h1>Hello, {name}!</h1>
-            <input value={name} onChange={(e) => setName(e.target.value)} />
-          </main>
-        );
-      }
-    `,
-    "/app/src/main.jsx": `
-      import { createRoot } from 'react-dom/client';
-      import App from './App.js';
-      createRoot(document.getElementById('root')).render(<App />);
-    `,
-
-    // 2. The page. React comes from a CDN via an import map.
-    "/app/public/index.html": `<!doctype html>
-      <html>
-        <head>
-          <meta charset="utf-8" />
-          <title>Hello React</title>
-          <script type="importmap">
-            {"imports": {
-              "react": "https://esm.sh/react@18.3.1",
-              "react/jsx-runtime": "https://esm.sh/react@18.3.1/jsx-runtime",
-              "react-dom/client": "https://esm.sh/react-dom@18.3.1/client"
-            }}
-          </script>
-        </head>
-        <body>
-          <div id="root"></div>
-          <script type="module" src="/main.js"></script>
-        </body>
-      </html>`,
-
-    // 3. Compile every .jsx in src/ to plain ES modules in public/.
-    "/app/build.js": `
-      const Babel = require('@babel/standalone');
-      const fs = require('fs');
-
-      for (const file of fs.readdirSync('/app/src')) {
-        if (!file.endsWith('.jsx')) continue;
-        const { code } = Babel.transform(fs.readFileSync('/app/src/' + file, 'utf8'), {
-          filename: file,
-          presets: [['react', { runtime: 'automatic' }]],
-          sourceType: 'module',
-        });
-        fs.writeFileSync('/app/public/' + file.replace('.jsx', '.js'), code);
-        console.log('compiled', file);
-      }
-    `,
-
-    // 4. A plain static server.
-    "/app/server.js": `
-      const http = require('http');
-      const fs = require('fs');
-      const path = require('path');
-
-      http.createServer((req, res) => {
-        const url = req.url === '/' ? '/index.html' : req.url;
-        const file = path.join('/app/public', url);
-        if (!fs.existsSync(file)) { res.writeHead(404); res.end('not found'); return; }
-        const type = url.endsWith('.html') ? 'text/html' : 'text/javascript';
-        res.writeHead(200, { 'Content-Type': type });
-        res.end(fs.readFileSync(file));
-      }).listen(5173, () => console.log('listening on 5173'));
-    `,
-  },
-});
-
-// Install the compiler, compile, serve.
-await box.exec("npm install @babel/standalone", { cwd: "/app", timeoutMs: 600_000 });
-console.log((await box.exec("node build.js", { cwd: "/app" })).output);
-box.spawn("node server.js", { cwd: "/app" });
-await box.waitForPort(5173);
-
-// Publish it on a real host port and open that URL in your browser.
-const bridge = await box.expose(5173, { hostPort: 5173 });
-console.log(`open ${bridge.url}`);
-```
-
-```
-compiled App.jsx
-compiled main.jsx
-open http://127.0.0.1:5173
-```
-
-Open that URL and you get a working React app — typing in the input updates the heading. The
-JSX was compiled inside the container, the files live only in memory, and nothing was written to
-your disk.
-
-`examples/03-react-app.mjs` is the same idea with a nicer component and a `SIGINT` handler.
-
-### Python
-
-Python is the bundled, source-built CPython 3.13 WebAssembly runtime mounted on the container's filesystem:
-
-```ts
-await box.exec("python3 -c \"print(open('/etc/hostname').read())\"");
-await box.exec("python3 /app/script.py arg1 arg2");
-await box.exec("echo '1 2 3' | python3 -c \"import sys; print(sum(map(int, sys.stdin.read().split())))\"");
-```
-
-The bundled standard library includes `json`, `re`, `os`, `sys`, `math`, `random`, `hashlib`,
-`binascii`, `struct`, `time`, `collections`, `itertools`, `functools`, `asyncio` and more. It is
-It is real CPython, so `sqlite3`, `dataclasses`, `decimal`, `typing`, `ssl`, and
-`asyncio` work. `pip` installs compatible wheels into the same filesystem and
-creates their `console_scripts` in `/usr/local/bin` (with outbound networking
-enabled). Native extensions still need an Emscripten-compatible build.
-
-### WebAssembly binaries
-
-Anything compiled to `wasm32-wasi` runs as a normal container process — same filesystem, same
-environment, same pipes:
-
-```ts
-await box.fs.writeFile("/usr/local/bin/tool", await readFile("tool.wasm"), { mode: 0o755 });
-await box.exec("tool --version");
-await box.exec("cat data.csv | tool summarise | sort");
-```
-
-An executable `.wasm` file is dispatched automatically, the way a `#!` script is — `./tool.wasm`
-runs without naming an interpreter, and a binary installed into `$PATH` under a bare name is
-found by its magic number. You can also invoke the interpreter directly:
-
-```
-wasi [--dir PATH] [--mapdir GUEST=PATH] [--env K=V] MODULE.wasm [args...]
-```
-
-By default the module sees the whole filesystem. `--dir` and `--mapdir` replace that with exactly
-what you list, and a path that climbs out of a preopened directory is refused with `ENOTCAPABLE`.
-
-Building one, with any wasi-sdk clang:
-
-```bash
-clang --target=wasm32-wasip1 --sysroot="$WASI_SYSROOT" -O2 tool.c -o tool.wasm
-```
-
-Two things to know, both of which match how `wasmtime` behaves:
-
-- **A WASI program has no working directory.** wasi-libc fixes its own at `/`, so a guest's
-  relative path resolves from the root. Pass absolute paths.
-- **Sockets report `ENOTSUP`.** This container's network is an HTTP router rather than a packet
-  path, so a guest that wants to `bind()` cannot. Files, clocks, randomness, arguments,
-  environment and standard I/O all work.
-
-Standard input is drained before the module starts, because WASI's `fd_read` is synchronous and
-the container's streams are not — so piping and redirection work, but a wasm program reading a
-live terminal sees end-of-file.
-
-### Filesystem from the host
+Files in and out, snapshots, and a terminal you can wire to xterm.js:
 
 ```ts
 await box.fs.writeFile("/app/config.json", JSON.stringify(config));
-const log = await box.fs.readFile("/var/log/app.log", "utf8");
-const entries = await box.fs.readdir("/app");
-const { files, bytes } = await box.fs.usage("/app");
+const snapshot = box.snapshot();              // serialisable; restore() later
 
-await box.copyIn("./my-project", "/app");     // host → container
-await box.copyOut("/app/dist", "./dist");     // container → host
-```
-
-### Snapshots
-
-```ts
-const snapshot = box.snapshot();   // serialisable
-await box.restore(snapshot);
-```
-
-### Interactive terminals
-
-`Terminal` is transport-agnostic: feed it keystrokes, it hands you back what to display. That
-works for a real TTY and for xterm.js in a browser alike.
-
-```ts
 import { Terminal } from "sandboxedjs";
-
-const terminal = new Terminal(box.session(), {
-  write: (data) => xterm.write(data),
-  columns: 80,
-  rows: 24,
-});
-xterm.onData((data) => terminal.input(data));
+const terminal = new Terminal(box.session(), { write: (d) => xterm.write(d), columns: 80, rows: 24 });
+xterm.onData((d) => terminal.input(d));
 terminal.start();
 ```
 
-You get line editing, history, tab completion over commands and paths, multi-line continuation,
-and the usual control keys.
+> **Outbound access is off by default.** `npm install`, `pip install` and `npx <new tool>` all fail
+> until you pass `network: { allowOutbound: true }`. This is the single most common surprise.
 
-## Command line
+## Running a full-stack project in a browser
 
-```bash
-npx sandboxedjs --repl                     # explore: what runs, what doesn't
-npx sandboxedjs                            # interactive shell
-npx sandboxedjs -c 'ls -la /etc'           # one command
-npx sandboxedjs script.sh                  # run a script
-npx sandboxedjs -v ./app:/app -w /app      # mount a host directory
-npx sandboxedjs --network -p 3000          # allow outbound, publish a port
-```
+This is the case most people arrive for: a Vite frontend and a Python backend, in one container, in
+a tab — the frontend calling `http://localhost:8000`, the backend calling a real API.
 
-Run `sandboxedjs --help` for the full list.
+Two different problems hide in that sentence, and SandboxedJS solves them in two different ways.
 
-### Trying it out
+### 1. Frontend → backend: nothing to configure
 
-`--repl` drops you into a shell with a summary of what this container can actually do. Every
-line is measured on the spot rather than claimed, so a runtime that is missing says so:
-
-```
-sandboxedjs — a Linux-like container inside Node.js
-
-  node      v22.12.0      npm, require, http servers
-  python3   CPython 3.13  only WebAssembly-built C extensions
-  ffmpeg    5.1.4         video and audio
-  wasi      preview1      run wasm32-wasi binaries; ./tool.wasm works
-  network   on            npm install reaches the real registry
 ```
-
-It needs no project and no files — it is meant for finding the edges. Because installing
-packages is most of what people want to test, `--repl` allows outbound access; pass
-`--no-network` to take it away and watch what breaks.
-
-## Security
-
-The container has no access to your filesystem, environment, or network unless you grant it:
-
-- The filesystem is entirely in memory. Code inside cannot read or write a host path — there is
-  no `/Users`, no `/home/you`, no way to reach one.
-- Outbound network access is **off by default**; `curl https://…` fails until you pass
-  `network: { allowOutbound: true }`, optionally narrowed with `allowedHosts`. The same policy
-  binds a program's own `fetch`, `http`, `https` and `WebSocket`: a refused request fails with
-  `ENETUNREACH`. `localhost` and `127.0.0.1` always mean the container's own servers — never the
-  host's.
-- Host files enter only through `files`, `mount()` or `copyIn()`, and leave only through
-  `copyOut()` or `fs.readFile()`.
-- `timeoutMs` bounds runaway commands, and `exec` settles even when a process ignores its kill
-  signal.
-
-### The in-container user model does not constrain Node.js
-
-This one matters, so it gets its own heading. The Unix permission layer is enforced for the
-shell, the coreutils and Python:
-
-```ts
-await box.exec("cat /root/secret", { user: "agent" });                      // Permission denied
-await box.exec("python3 -c \"open('/etc/passwd','a')\"", { user: "agent" }); // OSError
+frontend (:3000) ──▶ http://localhost:8000/agent/run ──▶ FastAPI (:8000)
 ```
 
-It is **not** enforced for Node.js. A `node` script gets direct access to the underlying volume,
-so it can read and write any path in the container regardless of `user`:
+Both servers are inside the container, so `localhost:8000` is *true there* — it means the
+container's own backend, never your machine's. Leave the URL exactly as the project writes it. In a
+live preview, an injected script rewrites loopback addresses to the preview's origin and the
+service worker routes them back in by port, so the same code works in the frame without a proxy
+config, a rewrite rule or an environment variable.
 
 ```ts
-await box.exec("node -e \"require('fs').readFileSync('/root/secret')\"", { user: "agent" }); // succeeds
-```
-
-Node code runs on the JavaScript runtime, which owns its own volume and has no notion of
-container uids. Treat `user` as a way to model *ordinary* multi-user behaviour, not as a
-privilege boundary for JavaScript you do not trust. If untrusted JavaScript must not see
-something, keep it out of the container rather than relying on file modes.
+import { createContainer, createPreview } from "sandboxedjs";
 
-The runtime also shares the host's JavaScript realm today rather than running in a worker, so a
-program inside the container can reach host globals. Isolating it in a worker is planned; until
-then, do not treat the container as a boundary against hostile code.
+// `allowOutbound` is still what lets the project install and call out at all;
+// the proxy is how those calls leave a browser, not permission to make them.
+const box = await createContainer({ files: project, network: { allowOutbound: true } });
 
-### And it is not a VM
+await box.exec("pip install -r requirements.txt", { cwd: "/app/backend", timeoutMs: 600_000 });
+await box.exec("npm install", { cwd: "/app/frontend", timeoutMs: 600_000 });
 
-Everything runs in your Node process, so a true sandbox escape is a JavaScript-engine escape.
-This is isolation from mistakes and from ordinary untrusted programs — not a substitute for a
-VM or a real container when facing a determined attacker.
-
-## Troubleshooting
-
-**`npm install` or `npx <tool>` fails immediately.**
-You almost certainly did not pass `network: { allowOutbound: true }`. It is off by default, so
-the container cannot reach registry.npmjs.org. This is the most common surprise by far.
+box.spawn("fastapi run", { cwd: "/app/backend" });
+box.spawn("npm run dev", { cwd: "/app/frontend" });
+await box.waitForPort(3000, { timeoutMs: 60_000 });
 
-```ts
-const box = await createContainer({ network: { allowOutbound: true } });
+const preview = await createPreview(box);      // null where service workers are unavailable
+iframe.src = preview!.urlFor(3000);
 ```
 
-Narrow it if you like: `network: { allowOutbound: true, allowedHosts: ["registry.npmjs.org"] }`.
+It works between preview pages and from another tab of the same browser while the owner page is
+open. It does not work from Postman, curl or another machine — the container *is* the tab; there is
+no server anywhere to reach.
 
-**`command not found` for something you installed.**
-Check where it landed. `npm install` installs into the nearest `package.json` directory, so run
-it with the right `cwd`:
+### 2. Backend → the internet: one file, once
 
-```ts
-await box.exec("npm install express", { cwd: "/app" });
-await box.exec("ls node_modules/.bin", { cwd: "/app" });
 ```
-
-**A server started with `spawn` never answers.**
-Wait for it rather than racing it:
-
-```ts
-box.spawn("node server.js", { cwd: "/app" });
-await box.waitForPort(3000, { timeoutMs: 60_000 });
+FastAPI ──▶ https://ollama.com ──✗ blocked by the browser (no CORS headers)
+FastAPI ──▶ egress proxy on your own origin ──▶ https://ollama.com ──✓
 ```
 
-**`exec` hangs on a command that reads stdin.**
-`exec` gives a command an empty stdin unless you pass some. `box.exec("cat")` with no `stdin`
-returns immediately; `box.spawn("cat")` gives you a live pipe to write into.
-
-**Output looks wrong when piping.**
-Pass `tty: true` only when you want terminal behaviour (colour, column layout). Without it,
-`ls` emits one name per line, like a real pipe.
-
-**A command runs forever.**
-Set `timeoutMs`, per call or as a container default. `exec` settles even if the process ignores
-its kill signal.
-
-## Running in a browser
+A page may only read a response from a host that sends CORS headers, and most APIs send none — an
+`Authorization` header alone forces a preflight plenty of them answer with 405. That is the
+browser's rule about *pages*, not a container limit, and the only way through it is a request made
+somewhere a page is not. So add one to the project you already deploy:
 
-The same `createContainer()` API runs under Node and in modern browsers. Browser execution is
-tested under Vite 8; the remaining browser-specific limits are listed below.
+```bash
+npx sandboxedjs-egress init --allow ollama.com,api.openai.com
+```
 
-**Done — the package no longer hard-depends on Node at import time.** Compression and hashing
-resolve their implementation at call time (`node:zlib`/`node:crypto` on Node,
-`CompressionStream`/`crypto.subtle` plus a JS MD5 in a browser), so nothing pulls a `node:`
-builtin in when the module loads and a bundler will not fail on it.
+That writes a single function file at the path your host serves — Cloudflare Pages, Vercel and
+Netlify are detected, `--target` names one. Nothing else changes: a container in a browser probes
+its own origin for that proxy before giving up, so **no project passes a `proxy` option and no
+project is configured twice.**
 
-**One call, either side.** `createContainer()` boots its own runtime. There is no host to pick
-and no pod to pass:
+| Where you are | What to do |
+|---|---|
+| Deployed (Pages, Vercel, Netlify) | `npx sandboxedjs-egress init --allow …`, then deploy |
+| Developing | `npx sandboxedjs-egress` — the probe checks its port |
+| You already have a server | `app.use(EGRESS_PATH, egressNodeHandler({ allow: [...] }))`, before any body parser |
+| Using `npx sandboxedjs-serve` | Nothing; it mounts the proxy itself |
+| Node, not a browser | Nothing; there is no CORS to work around |
 
 ```ts
-import { createContainer } from "sandboxedjs";
-
-const box = await createContainer({ files: { "/app/index.js": "console.log(1)" } });
+// Your own Express/Node server:
+import { egressNodeHandler, EGRESS_PATH } from "sandboxedjs/egress";
+app.use(EGRESS_PATH, egressNodeHandler({ allow: ["ollama.com"] }));
 
-await box.exec("ls -la /");      // shell + coreutils
-await box.exec("node app/index.js");
+// A static host — this is what `init` writes for you:
+import { handleEgressRequest } from "sandboxedjs/egress";
+export const onRequest = ({ request }) => handleEgressRequest(request, { allow: ["ollama.com"] });
 ```
 
-**Verified in a browser.** Booted under Vite 8, a container starts in the page and the shell,
-coreutils, virtual filesystem and Node runtime all work:
+Every exit honours it — `curl`, `wget`, a guest's `fetch`, Python's sockets and `httpx` — so it
+means the same thing whatever the project is written in. Loopback still stays inside the container,
+and the container's own policy still applies first: the proxy widens what a *page* can reach, never
+what the container is allowed to.
 
-```
-$ uname -a               Linux sandbox 5.10.0 (sandboxedjs@sandbox) … x86_64 GNU/Linux
-$ ls -la /               the full FHS tree
-$ node -p process.version  v22.12.0
-$ cat /etc/os-release    SandboxedJS 1.0 (sandbox)
-```
+> ⚠️ Anything that can reach the proxy can make requests through it carrying whatever credentials
+> the project holds. Keep the `allow` list set, keep the dev proxy on loopback, and put a deployed
+> one behind your app's authentication.
 
-**Vite 8 works through Rolldown's official WASI binding.** Because that binding uses shared
-WebAssembly memory and workers, the page must be cross-origin isolated. For example:
+### 3. The page itself must be cross-origin isolated
+
+Shared memory and threads need two headers on the **host page**, before `createContainer()` runs —
+no meta tag or polyfill can add them later:
 
 ```ts
 // vite.config.ts
@@ -751,452 +206,178 @@ export default {
     "Cross-Origin-Opener-Policy": "same-origin",
     "Cross-Origin-Embedder-Policy": "require-corp",
   } },
-  // Required as well — see below.
-  optimizeDeps: { exclude: ["@rolldown/binding-wasm32-wasi"] },
+  optimizeDeps: { exclude: ["@rolldown/binding-wasm32-wasi"] },  // see below
 };
 ```
 
-Production hosting must return the same two headers. Without them SandboxedJS reports a direct
-configuration error when Vite/Rolldown starts.
-
-`optimizeDeps.exclude` matters just as much, and fails less obviously. The binding starts its
-WASI worker with `new Worker(new URL("@rolldown/binding-wasm32-wasi/wasi-worker-browser.mjs",
-import.meta.url))`. A bundler that pre-bundles the package rewrites that URL to a path inside its
-own dependency cache, where the worker file does not exist — so the dev server answers with
-`index.html` and the browser rejects it for its MIME type, several layers away from anything that
-mentions Rolldown. Excluding the binding leaves it served from `node_modules`, where that URL
-resolves. The compiler is loaded only when an installed
-project actually contains Rolldown, so ordinary container boot does not pay its WASM startup cost.
-
-Host-backed compiler promises now count as active process work. The runtime keeps the guest
-alive while WASM initialization/build operations are pending, rather than guessing a startup
-delay from unreferenced timers. Listening servers remain live until closed, unreferenced, or
-killed. Cancellation releases owned child processes and ports, including children behind
-synchronous `npm`/`npx` wrappers; inherited terminal input bypasses a blocked parent worker.
-These are runtime lifecycle rules, not Vite-specific command replacements.
-
-**Not done — these things still stand between this and a complete browser IDE.**
-
-- *Preview isolation.* `createPreview()` registers the bundled service worker and routes HTTP
-  and WebSocket traffic into the container. It is an origin-local preview for trusted code:
-  scripts in the frame share your origin. Serve it from a separate origin for anything you
-  did not write.
-- *Complete worker isolation.* Worker-capable programs run off the main thread, but host-backed
-  compiler modules can require the local runtime. Container code is not a security boundary
-  from the host page; do not treat it as one.
-- *esbuild-dependent tools.* The runtime cannot execute any build of esbuild itself: one dlopens a compiled addon,
-  the other drives a Go program through facilities the sandbox does not have. On Node it borrows
-  the host's `esbuild-wasm`. Vite 8's Rolldown path works in a browser, but tools which call
-  esbuild directly still fail until esbuild-wasm runs *inside* the sandbox.
-
-Vite prints two warnings about `util` being externalized. They come from `readable-stream`, which
-declares `"util": false` for browsers and falls back on its own; nothing in this package imports
-it.
-
-Everything else is already browser-shaped. Nothing in the runtime imports a `node:` builtin except
-through an explicitly Node-only path that returns `null` elsewhere, compression and hashing pick
-their implementation at call time, and the module engine, volume, HTTP stack and npm installer are
-built on `fetch`, `acorn`, `resolve.exports`, `@noble/hashes` and `pako`.
-
-**What does not work in a browser:**
-
-- `copyIn()` / `copyOut()` — they read and write the host filesystem, which does not exist.
-- `expose()` — it opens a real `node:http` listener. Use `request()` to reach an in-container
-  server instead of a host port.
-- The `sandboxedjs` CLI, obviously.
-
-Those use dynamic imports, so they only fail if you call them.
-
-### Python in a browser
-
-Python works lazily in a browser without extra configuration. The owned CPython
-runtime and its pthread worker are shipped with the npm package:
+Production hosting needs the same two headers. For a built app, `npx sandboxedjs-serve ./dist 4173`
+serves it with them already set (and the egress mounted).
 
-```ts
-const box = await createContainer();
-await box.exec("python3 -c 'import sqlite3; print(sqlite3.sqlite_version)'");
-```
+That is the whole setup: two headers, one `init`, and projects that run unmodified.
 
-Pyodide remains available as an explicit compatibility backend:
+## Running in a browser
 
-```ts
-import { configurePython, createContainer } from "sandboxedjs";
+`createContainer()` is the same call on both sides — there is no host to pick and no pod to pass.
+Compression and hashing choose their implementation at call time, so no `node:` builtin is pulled in
+when the module loads and bundlers do not trip over it.
 
-configurePython({
-  backend: "pyodide",
-  pyodideURL: "https://cdn.jsdelivr.net/pyodide/v0.28.3/full/pyodide.mjs",
-  indexURL: "https://cdn.jsdelivr.net/pyodide/v0.28.3/full/",
-});
+**Vite 8 works in a browser host** through Rolldown's official WASI binding. `optimizeDeps.exclude`
+above matters as much as the headers: a pre-bundled binding rewrites its worker URL into the
+dependency cache, where the worker file does not exist, and the failure surfaces as an unrelated
+MIME-type error.
 
-const box = await createContainer();
-await box.exec("python3 -c 'import sqlite3; print(sqlite3.sqlite_version)'");
-```
+**Python works with no extra configuration** — the CPython runtime and its worker ship in the
+package. `pip install` resolves pure-Python wheels and the ABI-matched builds bundled for Pydantic 2,
+so FastAPI installs as it does anywhere. Packages with C, Cython, Rust or Meson extensions are built
+from source where a wheel does not exist; browsers have no compiler, so they ask one:
+`npx sandboxedjs-build-wheels 4180`. See [docs/python/build-on-miss.md](docs/python/build-on-miss.md)
+and [compatibility](docs/python/compatibility.md).
 
-Python never falls back to a host interpreter. When selecting the optional
-Pyodide backend, its module and asset directory must use the same version.
+**What does not work in a browser:** `copyIn()` / `copyOut()` and `expose()` (they need a real
+filesystem and a real socket), and the CLI. They fail only if you call them.
 
-The ABI-matched Pydantic Core wheels are embedded in the package's JavaScript
-bundle, so Vite and other bundlers do not need to copy or serve a separate
-wheel directory. `configurePython({ wheelIndex })` remains available for a
-private index containing additional native extensions.
+### Showing what runs
 
-## Uploading files
+| Need | Use | Runs guest code on your origin? |
+|---|---|---|
+| One response as data | `box.request(port, init)` | No — nothing executes |
+| One response rendered safely | `renderInto(box, el, { port })` | No — opaque-origin iframe, no `allow-same-origin` |
+| A whole site with real URLs | `createPreview(box)` → `urlFor(port)` | **Yes** — trusted code only |
 
-A file picker in a browser never hands over a path — it hands over the file's bytes. So getting a
-picked file into the container is an ordinary write, and there is nothing to mirror from the host
-disk.
+`createPreview` is what makes a dev server work: requests route by *which client is asking*, so
+`/src/main.js` and `/@vite/client` resolve without rewriting anything, and a tunnelled `WebSocket`
+carries HMR. Serve it from a separate origin for code you did not write. On Node, `box.expose(port)`
+gives a real loopback URL instead. Full lifecycle notes: [Server previews](docs/server-previews.md).
 
-Two ways in, both byte-exact:
+## Command line
 
-```js
-// 1. Directly, when your own server received the upload.
-await box.fs.writeFile("/workspace/uploads/clip.mp4", bytes);   // creates missing directories
+```bash
+npx sandboxedjs --repl                # explore: every line measured, not claimed
+npx sandboxedjs                       # interactive shell
+npx sandboxedjs -c 'ls -la /etc'      # one command
+npx sandboxedjs -v ./app:/app -w /app # mount a host directory
+npx sandboxedjs --network -p 3000     # allow outbound, publish a port
+
+npx sandboxedjs-serve ./dist 4173     # host a built app with the right headers
+npx sandboxedjs-egress init           # add the outbound proxy to a deployment
+npx sandboxedjs-build-wheels 4180     # build Python wheels a browser cannot
 ```
 
-The `File` returned by a browser picker can be passed directly too. It is read
-as bytes and written at the exact container path, including an application-
-generated temporary path:
+## For AI agents
 
-```js
-const picked = input.files[0];
-const sourcePath = "/tmp/transcribe-quran-52fjch/source-1786307713702-baleela.f32le";
-await box.fs.writeFile(sourcePath, picked);
-```
+`SandboxedJsBackend` plugs a container into
+[LangChain Deep Agents](https://github.com/langchain-ai/deepagents) as its execution and filesystem
+sandbox — shell plus `ls`, `read`, `write`, `edit`, `grep`, `glob`, `delete`, upload and download
+(absolute paths only). It mirrors `deepagents@1.13.2`'s `SandboxBackendProtocolV2`; `deepagents` is
+not a runtime dependency, so install it alongside your model provider.
 
-Do not pass `picked.path` (or any other host path) to a command in the
-container. Browser file pickers provide file data, not a path the sandbox can
-see.
+```ts
+import { SandboxedJsBackend, installSandboxSkills } from "sandboxedjs/agent";
 
-```js
-// 2. Through a server running inside the container — a picker in the previewed
-//    app posting to its own backend. Publish the port and upload normally.
-const bridge = await box.expose(3000);
-await fetch(`${bridge.url}/api/upload`, { method: "POST", body: file });
+const box = await createContainer({ cwd: "/app", network: { allowOutbound: true } });
+await installSandboxSkills(box);
+const agent = createDeepAgent({ model, backend: new SandboxedJsBackend(box, { cwd: "/app" }) });
 ```
 
-Either way the file lands on the container's filesystem, and `ffmpeg`, Node and Python all see the
-same bytes. Uploads are held in memory like the rest of the filesystem, so a very large video is
-bounded by RAM.
-
 ## Video and audio
 
-`ffmpeg` and `ffprobe` are FFmpeg 5.1 compiled to WebAssembly, mounted on the container's own
-filesystem. The mount is the point: inputs and outputs are ordinary container files, so nothing
-is staged in or copied back and a pipeline can be built out of scripts and pipes as usual.
-
-The runtime is ~31MB of WebAssembly, which is a lot to force on someone who wants a shell, so it
-installs separately. Without it the commands report themselves as missing, exactly as a real
-system reports an uninstalled binary:
-
-```bash
-npm install @ffmpeg/core
-```
+`ffmpeg` and `ffprobe` are FFmpeg 5.1 compiled to WebAssembly, mounted on the container's
+filesystem — inputs and outputs are ordinary container files, so pipelines work as usual. It is
+~31 MB of WASM, so it installs separately (`npm install @ffmpeg/core`); without it the commands
+report themselves missing, as a real system does.
 
 ```js
-const box = await createContainer({ cwd: "/media" });
-
-// Make a clip, then transcode it — both files are just container files.
 await box.exec("ffmpeg -f lavfi -i testsrc=size=640x480:rate=25:duration=5 -pix_fmt yuv420p clip.mp4");
 await box.exec("ffmpeg -i clip.mp4 -vf scale=320:-2 -frames:v 1 thumb.png");
-
-const thumbnail = await box.fs.readFile("/media/thumb.png");
-```
-
-Every FFmpeg invocation gets a fresh WebAssembly instance, because FFmpeg ends by calling
-`exit()` and tears its runtime down as it goes; the compiled module is cached, so only the cheap
-half is repeated. Runs are synchronous — a long transcode occupies the thread until it finishes.
-
-Two caveats worth knowing:
-
-- **`ffprobe` does not report an exit status.** Whenever it does real work this build leaves
-  through `exit()` without setting a return value, so success and failure are indistinguishable
-  to the caller. It is reported as success; branch on its *output*, not its exit code. `ffmpeg`
-  itself reports status correctly and can be relied on in `&&` chains.
-- **No hardware acceleration and no native codecs** beyond what the WebAssembly build ships.
-
-## Reaching a container's servers from the page
-
-A server inside the container is not on the network, so there is no `http://localhost:5173`
-your page can navigate to. There are three ways to reach one, and the right choice depends on
-whether you need a whole site or a single response — and on whether you trust the code.
-
-**1. One response, into a variable.** `request()` speaks to a server directly and hands back the
-bytes. Nothing is executed, so there is nothing to be careful about.
-
-```ts
-const res = await box.request(5173, { path: "/api/items" });
-element.textContent = res.body;          // text
-const items = res.json<Item[]>();        // parsed
-const bytes = res.bytes;                 // exact bytes, for images and source maps
-```
-
-**2. One response, rendered — safely.** `renderInto` puts the response in an iframe with
-`sandbox="allow-scripts"` and deliberately *without* `allow-same-origin`. The document lands in an
-opaque origin: its scripts run, and they can reach neither your DOM nor your cookies and storage.
-
-```ts
-import { renderInto } from "sandboxedjs";
-await renderInto(box, document.querySelector("#preview")!, { port: 5173 });
-```
-
-This is the option to reach for when the code came from somewhere you do not control. Its limit is
-that only that one response exists — a page asking for `/main.js` gets nothing, because there is no
-origin to serve it from. Good for generated HTML, a chart, a rendered document.
-
-**3. A whole site, with real URLs.** `createPreview` registers a service worker that gives the
-container's ports working URLs, so an iframe can load a dev server with all its subresources.
-
-```ts
-import { createPreview } from "sandboxedjs";
-const preview = await createPreview(box);          // null where service workers are unavailable
-iframe.src = preview!.urlFor(5173);
 ```
 
-Requests are routed by *which client is asking* rather than by path, so a dev server's absolute
-URLs — `/src/main.js`, `/@vite/client` — resolve without rewriting anything.
+Two caveats: `ffprobe` exits without setting a status, so branch on its output rather than its exit
+code; and there is no hardware acceleration or codec beyond what the WASM build ships.
 
-> **This one runs guest code on your origin.** A service worker can only serve URLs under the
-> origin that registered it, so scripts in the preview can reach `window.parent`, your cookies and
-> your `localStorage`. The sandbox contains a program's *filesystem and process table*, not the
-> page it serves. Use it for code you trust; for anything else, serve the preview from a separate
-> origin (a subdomain pointed at the same app) or stay with option 2.
+## Security — read this part
 
-**WebSockets, and why the HTML is modified.** A service worker can answer `fetch`; it cannot
-answer a WebSocket handshake, because no browser ever shipped that. So a previewed page is handed
-a `WebSocket` that tunnels through the host page into the container, injected as one `<script>` at
-the top of `<head>`. URLs that do not name the container keep the native implementation.
+The container has nothing until you grant it: the filesystem is memory (there is no `/Users` to
+reach), outbound access is off, `localhost` always means the container itself, and host files enter
+only through `files`, `mount()` or `copyIn()`.
 
-```ts
-const preview = await createPreview(box, { websocket: false });  // serve HTML byte for byte
-```
+What it is **not**:
 
-This is what makes HMR work. Without it Vite loses more than hot reload: it loses the only channel
-it has for telling a page that its dependency hashes are stale, which it needs after re-optimizing
-dependencies — and the frame is then stranded on `504 Outdated Optimize Dep` with every module
-failing and nothing to explain it. If you turn injection off, pass `onStale` to reload the frame
-yourself.
+- **Not a VM.** Everything runs in your JavaScript engine. A true escape is an engine escape. This
+  is isolation from mistakes and ordinary untrusted programs, not from a determined attacker.
+- **The user model does not constrain Node.** `user: "agent"` is enforced for the shell, the
+  commands and Python — `cat /root/secret` is denied for real. It is *not* enforced for `node`,
+  which reaches the volume directly. Model ordinary multi-user behaviour with it; do not treat it
+  as a privilege boundary for JavaScript you do not trust.
+- **A preview shares your origin.** `createPreview` serves guest code from the page that registered
+  the service worker, so its scripts can reach your DOM, cookies and storage. Use `renderInto` or a
+  separate origin for code you did not write.
 
-The container side is a real socket, not a Vite shim: `http` servers emit `upgrade` with a duplex
-socket, so `ws` and `socket.io` work unmodified. To speak to one from your own code rather than
-from a previewed page, use `box.connect(port, init, peer)`.
+By default each guest program does run on its own thread in a Worker, so it cannot reach your page's
+globals and `execSync` works. Without cross-origin isolation (or where a bundler moved the guest
+bundle) the runtime falls back to your realm and reports why; `isolation: "worker"` refuses to boot
+instead of falling back.
 
-Service workers need a secure context, and some embedded browsers disable them entirely — hence
-the `null` return rather than a throw. Responses are served with both
-`Cross-Origin-Resource-Policy` and `Cross-Origin-Embedder-Policy`, so a preview still frames
-correctly inside the cross-origin isolated page that Rolldown requires.
+## Known limits
 
-### Serving a built browser application
+An honest list:
 
-The host page must enable cross-origin isolation **before** `createContainer()` runs.
-This is a prerequisite for both synchronous child processes and threaded WASM; it is
-not something `npm create`, `npm install`, or `npm run` inside the container can fix.
-Headers configured on a development server do not carry over to a plain static server.
+- **No compiled native addons.** A `.node` file cannot load; a package needs a JS or WASM fallback.
+  `rollup` and `esbuild` get redirected to `@rollup/wasm-node` and `esbuild-wasm` automatically.
+- **esbuild cannot run *inside* the sandbox**, so tools that call it directly fail. On Node it
+  borrows the host's `esbuild-wasm`.
+- **Vite 8 / Rolldown is browser-only.** The Node binding preopens the real filesystem root and
+  cannot be handed another, so it looks for your project on the actual disk. Vite 7 works on both.
+  Two live browser projects need distinct absolute working directories.
+- **No raw sockets** — `net`, `tls`, TCP, UDP. HTTP servers run on a virtual stack, which is what
+  `request()`, previews and `expose()` speak to.
+- **Processes are cooperative.** `kill -9` cannot interrupt a tight synchronous loop; `SIGSTOP`
+  marks state. `chroot` runs the command in the target rather than isolating it.
+- **`execSync` needs the worker runtime.** Where it is unavailable, it throws naming the command —
+  answer *No* to prompts like `npm create vite`'s "Install and start now?" and run the steps from
+  the shell.
+- **`node:test`** covers what test files use (`test`/`describe`/hooks/`mock.fn`, spec and tap
+  reports); `run()`, coverage and mock timers are not implemented.
+- **Python has one shared site-packages** — no virtualenvs, no CPython pip. Use a fresh container for
+  dependency isolation. Native extensions must build for Emscripten.
+- **`expose()` does not proxy WebSockets**, so HMR does not reach a Node-hosted preview iframe.
 
-SandboxedJs ships a local browser host for built applications:
+## API at a glance
 
-```sh
-npx sandboxedjs-serve ./dist 4173
-```
+`createContainer(options)` takes `files`, `cwd`, `hostname`, `user`, `env`, `memory`, `cpus`,
+`network`, `timezone`, `timeoutMs`, `onStdout` / `onStderr`, `onServerReady`, `isolation`, `pod`
+and `python`.
 
-It serves the app on `http://127.0.0.1:4173` with COOP/COEP on documents, scripts,
-workers, and WASM. Missing assets return 404 rather than an HTML fallback. It binds
-to loopback by default and does not serve dotfiles or symlinks outside the web root.
-This is a local static host, not a production deployment server or SPA route rewriter.
+A `Container` gives you `exec` · `run` · `spawn` · `session` · `fs` · `mount` · `copyIn` / `copyOut`
+· `request` · `waitForPort` · `expose` · `connect` · `snapshot` / `restore` · `dispose`, plus
+`kernel`, `pod` and `net` as escape hatches.
 
-For a Node host integration (this subpath must not be imported into browser code):
+Commands are extensible, and a new one is a real file in `/usr/bin` — `which`, `man` and shebang
+dispatch all find it:
 
 ```ts
-import { serveBrowserApp, browserIsolationHeaders } from 'sandboxedjs/browser-host';
-const host = await serveBrowserApp({ directory: './dist', port: 4173 });
-console.log(host.url);
-// Or apply browserIsolationHeaders to your existing server's responses.
-// await host.close();
-```
+import { defineCommand } from "sandboxedjs";
 
-For remote deployments configure HTTPS plus those headers on your actual web server
-or CDN. Check `crossOriginIsolated` in the page, not just the network response: iframe
-permissions and embedded browser restrictions can still deny shared memory. A loaded
-page cannot grant itself this permission with a polyfill or a meta tag. Cross-origin
-resources also need CORS or an appropriate CORP policy under `require-corp`.
+box.kernel.installCommand(defineCommand({
+  name: "greet",
+  summary: "say hello",
+  run: (ctx) => (ctx.line(`hello ${ctx.args[0] ?? "world"}`), 0),
+}));
 
-Require worker support at boot when the application depends on synchronous Node APIs:
-
-```ts
-const box = await createContainer({ isolation: 'worker' });
+await box.exec("greet there | tr a-z A-Z");   // → HELLO THERE
 ```
 
-This rejects with the missing prerequisite or worker-load cause before commands run.
-The default `isolation: 'auto'` retains compatibility but reports fallback through
-`onRuntimeFallback(error)` (or `console.warn` if omitted). `isolation: 'realm'` is an
-explicit opt-out and does not support synchronous child processes.
-
-## Isolation
-
-By default each guest program runs on its own thread, in a Worker. The volume, the kernel, the
-coreutils and the process table stay on the thread that created the container, and the program
-reaches them through a `SharedArrayBuffer` channel it can wait on synchronously.
-
-Two things follow from that. Guest code no longer shares your page's realm, so it cannot reach
-your application's globals. And `child_process.execSync`, `spawnSync` and `execFileSync` work —
-they cannot be expressed any other way, because a synchronous call has to block its caller while
-the child it is waiting for still makes progress, which is impossible when both are the same
-thread.
-
-In default `auto` mode the runtime reports its fallback reason and stays usable:
-
-| Condition | What happens |
-|---|---|
-| `SharedArrayBuffer` unavailable, or the page is not cross-origin isolated | Falls back to the in-realm runtime |
-| The guest bundle cannot be loaded (a bundler moved or rewrote it) | Falls back to the in-realm runtime |
-| `modules` supplied by the host | Falls back — live JavaScript objects cannot cross a thread |
-| The project has `rolldown` installed | *That process* runs in-realm; the rest still get a thread |
-
-In a browser this needs the same COOP/COEP headers Rolldown does, which is the usual reason to
-find yourself in the fallback. `createContainer({ isolation: "realm" })` opts out entirely, and
-`workerUrl` points at the guest bundle when a bundler has moved it. Explicit
-`isolation: "worker"` rejects at boot instead of taking either environment fallback.
-Host-native module processes still use the realm runtime; selecting worker mode is
-not a guarantee that every package executes off the host thread.
-
-## Known limits
-
-Honest list of what does not work:
-
-- **Compiled native addons.** A `.node` file cannot be loaded, so a package that ships one has to
-  have a JavaScript or WebAssembly build to fall back on. `rollup` and `esbuild` do, and the
-  runtime redirects those two names to `@rollup/wasm-node` and `esbuild-wasm` automatically when
-  they are installed. Vite 8 is supported through Rolldown's official WASI build **in a browser
-  host** (with the two configuration steps above). Express, Koa, Fastify-style apps and plain
-  `http` servers also run.
-- **Vite 8 / Rolldown does not work when the host is Node.** The binding has two builds. The
-  browser one owns a `memfs` volume, which SandboxedJS mirrors the project into; the Node one
-  builds a `node:wasi` instance that preopens the *real* filesystem root, and there is no way to
-  hand it a different one. Rolldown therefore looks for `/app/my-app/index.html` on your actual
-  disk, does not find it, and the dev server answers every request with its fallback page. Vite 7
-  works on both hosts and is what the Node acceptance test pins.
-- **Concurrent browser Rolldown projects need distinct absolute working directories.** The
-  official binding owns one WASI memfs per page; SandboxedJS mirrors each project into it before
-  startup. Two live projects using the same path such as `/workspace` can overwrite that mirror.
-- **`child_process` is synchronous only under the Worker pod.** `spawn`, `exec` and `execFile`
-  always work and run through the kernel, so a child sees the same filesystem and coreutils as the
-  shell. `execSync`, `spawnSync` and `execFileSync` need the guest program to be on its own thread
-  — see *Isolation* above. Where it is, they work; where it is not, they throw
-  `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM` naming the command they were asked to run, and the way
-  through is to answer **No** to a prompt like `npm create vite`'s "Install with npm and start
-  now?" and run `npm install && npm run dev` from the shell instead.
-- **No `net`, `tls`, `worker_threads` or `vm`.** `http` and `https` are served by a virtual stack
-  that `request()` talks to directly, so servers work; raw sockets do not. A program can reach
-  servers anywhere in the container over HTTP (`http.get`, `fetch`), but not open a `WebSocket` to
-  one.
-- **`node:test` covers what test files use** — `test`/`it`, `describe`, hooks, subtests, `skip`,
-  `todo`, `only`, `mock.fn` and `mock.method`, with `spec` and `tap` reports — and `node --test`
-  finds and runs test files as Node 22 does. `run()`, coverage and mock timers are not
-  implemented. A test file exits when its tests finish, as under `--test-force-exit`.
-- **On the in-realm runtime, programs share one global object.** A global one program sets is
-  visible to the next. The worker runtime (the default where shared memory is available) gives
-  each program its own.
-- **Python is source-built CPython/WASM.** Each program gets its own interpreter
-  process worker. Pure-Python wheels install normally; native extensions must
-  be linked or published for Emscripten. The bundled wheel index includes the
-  ABI-matched `pydantic-core` builds required by Pydantic 2, so FastAPI resolves
-  against Pydantic 2 by default. Virtual environments and CPython's real pip
-  are not implemented; the sandbox `pip` installs into one shared site-packages
-  directory, so use a fresh container for dependency isolation.
-- **No real sockets.** HTTP servers work through the request proxy; raw TCP/UDP does not.
-- **No real processes.** Processes are cooperative async tasks: `kill -9` cannot interrupt a
-  tight synchronous loop, and `SIGSTOP` only marks state.
-- **`chroot` does not isolate**; it runs the command with its cwd inside the target.
-- **`awk`'s `system()`** does not block on the child.
-- **`expose()` does not proxy WebSockets**, so dev-server HMR and live-reload do not reach a
-  preview iframe. Reload the frame from your IDE after a rebuild instead — see
-  [Showing a live preview in an IDE](#showing-a-live-preview-in-an-ide).
-
-## API reference
-
-### `createContainer(options): Promise<Container>`
-
-| Option | Type | Default | |
-|---|---|---|---|
-| `files` | `Record<string, string \| Uint8Array>` | — | Seed the filesystem |
-| `cwd` | `string` | `"/"` | Default working directory, and base for relative `files` keys |
-| `hostname` | `string` | `"sandbox"` | |
-| `user` | `string \| null` | `"root"` | Login user; a non-root name gets uid 1000 and sudo |
-| `env` | `Record<string, string>` | — | Extra environment variables |
-| `memory` | `number` | 2 GiB | Reported by `free`, `top`, `/proc/meminfo` |
-| `cpus` | `number` | `4` | Reported by `nproc`, `/proc/cpuinfo` |
-| `network` | `NetworkOptions` | outbound off | `{ allowOutbound, allowedHosts, ipv4, gateway }` |
-| `timezone` | `string` | `"UTC"` | |
-| `timeoutMs` | `number` | none | Default limit for `exec` |
-| `onStdout` / `onStderr` | `(chunk: string) => void` | — | Container-wide output taps |
-| `onServerReady` | `(port, url) => void` | — | Fires when something inside starts listening |
-| `pod` | `RuntimePod` | booted for you | Share or substitute the JavaScript runtime |
-| `python` | `PythonOptions` | jsDelivr | Where to load Pyodide from |
-
-### `Container`
-
-| Member | |
-|---|---|
-| `exec(command, opts?)` | Run a shell command line; returns `{ stdout, stderr, output, exitCode, timedOut, durationMs }` |
-| `run(argv, opts?)` | Run a program without shell parsing |
-| `spawn(command, opts?)` | Start a process; returns `{ pid, stdin, stdout, stderr, wait(), kill() }` |
-| `session(opts?)` | A stateful shell session |
-| `fs` | `readFile`, `writeFile`, `readdir`, `mkdir`, `rm`, `stat`, `walk`, `usage`, … |
-| `mount(files, opts?)` | Add files after boot |
-| `copyIn` / `copyOut` | Move trees between host and container |
-| `request(port, init?)` | HTTP to an in-container server |
-| `waitForPort(port, opts?)` | Resolve once something is listening |
-| `expose(port, opts?)` | Bridge to a real host port |
-| `snapshot()` / `restore(s)` | Filesystem persistence |
-| `kernel`, `pod`, `net` | Escape hatches to the internals |
-| `hostname`, `user`, `cwd`, `env` | What the container was booted with |
-| `dispose()` | Tear everything down |
-
-Lower-level pieces — `Kernel`, `Vfs`, `Shell`, `Terminal`, `NetworkStack`, `defineCommand` — are
-exported too, so you can add your own commands or embed the shell on its own.
-
-### Adding a command
+`Kernel`, `Vfs`, `Shell`, `Terminal` and `NetworkStack` are exported too, if you want to embed a
+piece rather than the whole system.
 
-```ts
-import { createContainer, defineCommand } from "sandboxedjs";
-
-const box = await createContainer();
-
-box.kernel.installCommand(
-  defineCommand({
-    name: "greet",
-    summary: "say hello",
-    run(ctx) {
-      ctx.line(`hello ${ctx.args[0] ?? "world"}`);
-      return 0;
-    },
-  }),
-);
-
-await box.exec("greet there | tr a-z A-Z"); // → HELLO THERE
-```
+## More
 
-It becomes a real file in `/usr/bin`, so `which greet`, `man greet` and shebang dispatch all work.
+[`examples/`](./examples) — a REPL, an Express API, a React app, a Python pipeline, an agent
+sandbox, a browser terminal. [`docs/`](./docs) — previews, Python build and compatibility, browser
+runtime architecture, developer tool packs, frontend automation.
 
-## Examples
-
-See [`examples/`](./examples): a REPL, an Express API, a React app, a Python data pipeline, an
-agent sandbox, and a browser terminal.
+Optional packs add local Git (isomorphic-git), embedded Postgres (PGlite), integrity-checked WASI
+commands and frontend automation; see [developer tool packs](docs/developer-tool-packs.md).
 
 ## License
 
-MIT, with no dependency carrying a stricter licence.
-
-
-### Optional developer tool packs
-
-Host applications can add local Git operations through `createGitCommand`
-(isomorphic-git) and embedded PostgreSQL SQL through `createSqlCommand`
-(PGlite). These engines are optional and are not bundled into the core.
-`installWasmCommands` installs separately distributed, integrity-checked WASI
-commands. ELF files use registered compatibility, translation and emulation
-backends. Original experimental x86-64 engines are available as opt-in backends
-for a small freestanding instruction/syscall subset; see [Original engines](docs/original-x64.md).
-See [Developer tool packs](docs/developer-tool-packs.md) for examples and limits.
-`createFrontendPlaywright` adds Playwright-shaped, frontend-only automation of a
-same-origin iframe using the host browser; see
-[Frontend automation](docs/frontend-automation.md) for its supported subset.
+MIT — and no dependency carries a stricter one.