sandboxedjs 0.2.10 → 0.2.11

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="/assets/logo.png" alt="SandboxedJS" width="140" />
+<img src="assets/logo.png" alt="SandboxedJS" width="140" />
 
 # SandboxedJS
 
@@ -29,7 +29,7 @@ const box = await createContainer({
 });
 
 await box.exec("ls -la /app");
-await box.exec("node /app/hello.js");        // → hi from linux
+await box.exec("node /app/hello.js"); // → hi from linux
 await box.exec("python3 -c 'print(2**64)'"); // → 18446744073709551616
 
 box.dispose();
@@ -54,16 +54,16 @@ Node 18.17+. Pure JavaScript and WebAssembly — no build step, no native module
 
 ## What's inside
 
-| | |
-|---|---|
-| **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 |
+|                 |                                                                                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **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                            |
 
 One filesystem underneath all of it: a file written by `echo` is read by `require('fs')` and by
 Python's `open()`, in any direction.
@@ -71,13 +71,16 @@ Python's `open()`, in any direction.
 ## Quick tour
 
 ```ts
-const box = await createContainer({ cwd: "/app", network: { allowOutbound: true } });
+const box = await createContainer({
+  cwd: "/app",
+  network: { allowOutbound: true },
+});
 
 await box.exec("npm install express", { cwd: "/app", timeoutMs: 300_000 });
 box.spawn("node server.js", { cwd: "/app" });
 await box.waitForPort(3000);
 
-const res = await box.request(3000, { path: "/api" });   // talk to it from your code
+const res = await box.request(3000, { path: "/api" }); // talk to it from your code
 console.log(res.status, res.json());
 ```
 
@@ -87,17 +90,21 @@ A stateful shell, when `exec` alone is too forgetful:
 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
 ```
 
 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 snapshot = box.snapshot();              // serialisable; restore() later
+const snapshot = box.snapshot(); // serialisable; restore() later
 
 import { Terminal } from "sandboxedjs";
-const terminal = new Terminal(box.session(), { write: (d) => xterm.write(d), columns: 80, rows: 24 });
+const terminal = new Terminal(box.session(), {
+  write: (d) => xterm.write(d),
+  columns: 80,
+  rows: 24,
+});
 xterm.onData((d) => terminal.input(d));
 terminal.start();
 ```
@@ -118,7 +125,7 @@ Two different problems hide in that sentence, and SandboxedJS solves them in two
 frontend (:3000) ──▶ http://localhost:8000/agent/run ──▶ FastAPI (:8000)
 ```
 
-Both servers are inside the container, so `localhost:8000` is *true there* — it means the
+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
@@ -129,21 +136,27 @@ import { createContainer, createPreview } from "sandboxedjs";
 
 // `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 } });
+const box = await createContainer({
+  files: project,
+  network: { allowOutbound: true },
+});
 
-await box.exec("pip install -r requirements.txt", { cwd: "/app/backend", timeoutMs: 600_000 });
+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 });
 
 box.spawn("fastapi run", { cwd: "/app/backend" });
 box.spawn("npm run dev", { cwd: "/app/frontend" });
 await box.waitForPort(3000, { timeoutMs: 60_000 });
 
-const preview = await createPreview(box);      // null where service workers are unavailable
+const preview = await createPreview(box); // null where service workers are unavailable
 iframe.src = preview!.urlFor(3000);
 ```
 
 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
+open. It does not work from Postman, curl or another machine — the container _is_ the tab; there is
 no server anywhere to reach.
 
 ### 2. Backend → the internet: one file, once
@@ -155,7 +168,7 @@ FastAPI ──▶ egress proxy on your own origin ──▶ https://ollama.com
 
 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
+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:
 
 ```bash
@@ -167,13 +180,13 @@ Netlify are detected, `--target` names one. Nothing else changes: a container in
 its own origin for that proxy before giving up, so **no project passes a `proxy` option and no
 project is configured twice.**
 
-| 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 |
+| 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
 // Your own Express/Node server:
@@ -182,12 +195,13 @@ app.use(EGRESS_PATH, egressNodeHandler({ allow: ["ollama.com"] }));
 
 // A static host — this is what `init` writes for you:
 import { handleEgressRequest } from "sandboxedjs/egress";
-export const onRequest = ({ request }) => handleEgressRequest(request, { allow: ["ollama.com"] });
+export const onRequest = ({ request }) =>
+  handleEgressRequest(request, { allow: ["ollama.com"] });
 ```
 
 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
+and the container's own policy still applies first: the proxy widens what a _page_ can reach, never
 what the container is allowed to.
 
 > ⚠️ Anything that can reach the proxy can make requests through it carrying whatever credentials
@@ -202,11 +216,13 @@ no meta tag or polyfill can add them later:
 ```ts
 // vite.config.ts
 export default {
-  server: { headers: {
-    "Cross-Origin-Opener-Policy": "same-origin",
-    "Cross-Origin-Embedder-Policy": "require-corp",
-  } },
-  optimizeDeps: { exclude: ["@rolldown/binding-wasm32-wasi"] },  // see below
+  server: {
+    headers: {
+      "Cross-Origin-Opener-Policy": "same-origin",
+      "Cross-Origin-Embedder-Policy": "require-corp",
+    },
+  },
+  optimizeDeps: { exclude: ["@rolldown/binding-wasm32-wasi"] }, // see below
 };
 ```
 
@@ -238,13 +254,13 @@ filesystem and a real socket), and the CLI. They fail only if you call them.
 
 ### Showing what runs
 
-| 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 |
+| 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                       |
 
-`createPreview` is what makes a dev server work: requests route by *which client is asking*, so
+`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).
@@ -274,9 +290,15 @@ not a runtime dependency, so install it alongside your model provider.
 ```ts
 import { SandboxedJsBackend, installSandboxSkills } from "sandboxedjs/agent";
 
-const box = await createContainer({ cwd: "/app", network: { allowOutbound: true } });
+const box = await createContainer({
+  cwd: "/app",
+  network: { allowOutbound: true },
+});
 await installSandboxSkills(box);
-const agent = createDeepAgent({ model, backend: new SandboxedJsBackend(box, { cwd: "/app" }) });
+const agent = createDeepAgent({
+  model,
+  backend: new SandboxedJsBackend(box, { cwd: "/app" }),
+});
 ```
 
 ## Video and audio
@@ -287,7 +309,9 @@ filesystem — inputs and outputs are ordinary container files, so pipelines wor
 report themselves missing, as a real system does.
 
 ```js
-await box.exec("ffmpeg -f lavfi -i testsrc=size=640x480:rate=25:duration=5 -pix_fmt yuv420p clip.mp4");
+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");
 ```
 
@@ -305,7 +329,7 @@ What it is **not**:
 - **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`,
+  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
@@ -323,7 +347,7 @@ An honest list:
 
 - **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
+- **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.
@@ -333,7 +357,7 @@ An honest list:
 - **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
+  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.
@@ -357,13 +381,15 @@ dispatch all find it:
 ```ts
 import { defineCommand } from "sandboxedjs";
 
-box.kernel.installCommand(defineCommand({
-  name: "greet",
-  summary: "say hello",
-  run: (ctx) => (ctx.line(`hello ${ctx.args[0] ?? "world"}`), 0),
-}));
+box.kernel.installCommand(
+  defineCommand({
+    name: "greet",
+    summary: "say hello",
+    run: (ctx) => (ctx.line(`hello ${ctx.args[0] ?? "world"}`), 0),
+  }),
+);
 
-await box.exec("greet there | tr a-z A-Z");   // → HELLO THERE
+await box.exec("greet there | tr a-z A-Z"); // → HELLO THERE
 ```
 
 `Kernel`, `Vfs`, `Shell`, `Terminal` and `NetworkStack` are exported too, if you want to embed a

package/dist/index.cjs

@@ -21103,7 +21103,7 @@ var wheels_default = {
 
 // package.json
 var package_default = {
-  version: "0.2.10"};
+  version: "0.2.11"};
 
 // src/python/extension-abi.ts
 var EXTENSION_ABI = {

package/dist/index.js

@@ -21086,7 +21086,7 @@ var wheels_default = {
 
 // package.json
 var package_default = {
-  version: "0.2.10"};
+  version: "0.2.11"};
 
 // src/python/extension-abi.ts
 var EXTENSION_ABI = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandboxedjs",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "A Linux-like container that runs entirely inside Node.js — POSIX shell, ~140 coreutils, Node.js and Python runtimes, virtual filesystem and networking. No Docker, no VM, no native modules.",
   "type": "module",
   "license": "MIT",