kern-sandbox 0.1.1

package/README.md

@@ -0,0 +1,170 @@
+# kern-sandbox (Node.js / TypeScript)
+
+Run LLM/agent-generated code in a fast, **local**, daemonless kernel sandbox, straight from Node.
+
+It is a thin, dependency-free wrapper around the [`kern`](https://github.com/getkern/kern) binary:
+a fresh, isolated box per call, network off by default, hard resource caps, and a timeout the binding
+itself enforces. E2B/Firecracker territory, but local and about 1.6 MB, with no cloud, no account, no VM.
+
+```js
+const kern = require("kern-sandbox");
+
+// one-shot: a throwaway box, network off, hard caps, a timeout the binding enforces
+const r = await kern.runCode("print(sum(range(100)))");
+console.log(r.stdout, r.success); // "4950\n" true
+```
+
+TypeScript types ship in the box:
+
+```ts
+import { runCode, withSandbox, Sandbox } from "kern-sandbox";
+```
+
+## Install
+
+```sh
+npm install kern-sandbox
+```
+
+You also need the `kern` binary on `PATH` (or point `$KERN_BIN` at it). One line on Linux:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/getkern/kern/main/install.sh | sh
+```
+
+kern needs a Linux kernel with unprivileged user namespaces + cgroup v2. On Windows it runs under WSL2;
+on macOS, inside a Linux VM. Node 18+.
+
+## A session: files persist, processes are ephemeral
+
+File state lives in a workspace directory on the host, bind-mounted into every box. Each `runCode`/`run`
+spawns a **fresh** box on that shared workspace, so file state persists but in-memory state does not
+(write to disk for continuity). `withSandbox` opens the session and cleans it up, even on throw:
+
+```js
+await kern.withSandbox({ setup: "pip install pandas" }, async (sbx) => {
+  await sbx.writeFile("data.csv", csvBytes);
+  const r = await sbx.runCode(
+    "import pandas as pd; print(pd.read_csv('data.csv').describe())",
+  );
+  console.log(r.stdout);          // network off, capped, isolated
+  const chart = await sbx.readFile("out.png");
+});
+```
+
+`setup` is the **only** moment the network is on (a separate box that installs deps into the workspace
+and dies); every `runCode` after it is network-off.
+
+## Run JavaScript in the box too
+
+```js
+const r = await kern.runCode("console.log([1,2,3].map(x => x * x))", {
+  image: "node:20-slim",
+  language: "node",
+});
+```
+
+`language` is `"python"` (default), `"bash"`, or `"node"`. Match the image to the language.
+
+## The result
+
+`runCode`/`run` resolve to an `ExecutionResult`:
+
+| field | meaning |
+|---|---|
+| `stdout`, `stderr` | captured output (each capped at `maxOutputBytes`) |
+| `exitCode` | the process exit code |
+| `success` | `true` iff `exitCode === 0` **and** no sandbox fault |
+| `fault` | a sandbox event, or `null`. `{ type, message }` |
+| `files` | files created/modified in the workspace this call |
+| `truncated` | output hit the cap and overflow was discarded |
+
+A non-zero exit from *your code* is **not** a fault (`fault` stays `null`): it is a normal result.
+`fault` is only set when the **sandbox** acted:
+
+| `fault.type` | when |
+|---|---|
+| `timeout` | the call exceeded `timeoutS`; the binding killed the box |
+| `escape_blocked` | a syscall was blocked by the seccomp filter (SIGSYS) |
+| `killed` | the box was SIGKILLed, most often the cgroup OOM-killer |
+| `startup_failed` | kern could not start the box (bad image, pull error, ...) |
+
+```js
+const r = await kern.runCode("while True: pass", { timeoutS: 5 });
+r.success;      // false
+r.fault.type;   // "timeout"
+```
+
+## Safe by default
+
+Every relaxing option says so in its name or docs:
+
+- **network off** unless `network: true` (session-level, explicit).
+- **hard caps**: `memoryMb` (512), `pids` (256), optional `cpus`. Enforced by cgroup v2.
+- **timeout owned by the binding**: `timeoutS` (30) is a real deadline; the binding kills the box (and
+  its process group), so a `timeout` fault is a fact, not a guess.
+- **output bounded**: `maxOutputBytes` (64 MiB each) so a flooding box cannot exhaust host RAM.
+- **env off argv**: workload env is written to a private `0600` file, never `--env K=V` on the command
+  line, so a credential in `env` does not leak into `ps`.
+- **mounts refused**: sensitive host sources (`/`, `/etc`, `/root`, `/proc`, `/sys`, `/dev`, the docker
+  socket, `$HOME`) and escaping targets are refused even when asked.
+- **workspace I/O contained**: `writeFile`/`readFile` reject `..` escapes and open the final component
+  `O_NOFOLLOW`, so a symlink the box plants cannot redirect host I/O outside the workspace.
+
+### Options
+
+```ts
+new Sandbox({
+  image,           // default "python:3.12-slim"
+  setup,           // one-time, network-on, e.g. "pip install pandas"
+  workspace,       // host dir to persist; omit for a temp dir deleted on close()
+  memoryMb,        // default 512
+  cpus,            // default null (uncapped)
+  pids,            // default 256
+  timeoutS,        // default 30, MANDATORY per-call deadline
+  network,         // default false (RELAXES ISOLATION)
+  mounts,          // { hostSrc: boxTarget } or { src: [target, "ro"] }
+  profiles,        // reusable kern.toml profiles: ["vcpu:heavy", "vgpio:leds", "vdisk:scratch"]
+  env,             // { KEY: "value" }
+  maxOutputBytes,  // default 64 MiB
+  enforceLimits,   // default true (systemd scope, ~6 ms); false = best-effort, ~3 ms
+  depsReadonly,    // default false
+  onStdout,        // (chunk: Buffer) => void, live stdout streaming (result.stdout still captured)
+  onStderr,        // (chunk: Buffer) => void, live stderr streaming
+});
+```
+
+## Charts, live output, and checkpoints
+
+**Charts / artifacts (the "code interpreter" pattern).** No Jupyter kernel: have the code WRITE the
+artifact to the workspace, then read it back with `readFile`.
+
+```js
+await kern.withSandbox({ setup: "pip install matplotlib" }, async (sbx) => {
+  await sbx.runCode("import matplotlib; matplotlib.use('Agg')\n" +
+    "import matplotlib.pyplot as plt; plt.plot([1,4,9]); plt.savefig('chart.png')");
+  const png = await sbx.readFile("chart.png"); // Buffer, ready to return to the model / user
+});
+```
+
+**Live output.** Pass `onStdout` / `onStderr` to stream each chunk as it arrives. The callback is
+best-effort, not lossless: a SLOW callback drops chunks rather than applying backpressure to the box
+(the full capped output is always in `result.stdout`).
+
+**Checkpoints.** `sbx.snapshot(dest)` writes a portable `.tar.gz` of the workspace (a FILESYSTEM
+checkpoint, not memory); `sbx.restore(src)` extracts it back, refusing absolute / `..` / symlink
+members. Interoperable with `tar` and the Python binding (both write plain USTAR, so a workspace path
+must be under 100 bytes). The Node path uses a hand-rolled tar reader,
+so while it is new it is **opt-in**: set `KERN_SANDBOX_SNAPSHOT=1` to enable it (it fails closed with a
+clear error otherwise). The Python binding uses the stdlib `tarfile` and has no such gate.
+
+## Honest threat model
+
+kern is a **kernel-boundary** sandbox for **your own or semi-trusted** code (CI, dev, edge, your
+agents' code). Its seccomp filter is a **denylist**: right for semi-trusted agent code, **not** a hard
+boundary against deliberately hostile multi-tenant code. For that, reach for a microVM (Firecracker) or
+gVisor. See the project's [SECURITY.md](https://github.com/getkern/kern/blob/main/SECURITY.md).
+
+## License
+
+[Apache-2.0](https://github.com/getkern/kern/blob/main/LICENSE).

package/index.d.ts

@@ -0,0 +1,124 @@
+// Type definitions for kern-sandbox
+// Run LLM/agent-generated code in a fast, local, daemonless kernel sandbox.
+
+/** What stopped the code at the SANDBOX level. Reported as data on a result, never thrown. */
+export type SandboxFaultType = "timeout" | "escape_blocked" | "killed" | "startup_failed";
+
+export interface SandboxFault {
+  type: SandboxFaultType;
+  message: string;
+}
+
+/** A file in the workspace and how a step touched it. */
+export interface FileInfo {
+  /** workspace-relative path */
+  path: string;
+  size: number;
+  change: "created" | "modified";
+}
+
+/** The outcome of one runCode()/run(). `fault` is the source of truth for "did the sandbox act";
+ * `exitCode`/`stdout` are what the user's code did. `success` requires both clean. */
+export class ExecutionResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  durationMs: number;
+  /** null iff the sandbox did nothing: any non-zero exit is then the user's code, not a sandbox fault. */
+  fault: SandboxFault | null;
+  files: FileInfo[];
+  /** stdout/stderr hit the capture cap and overflow was discarded. */
+  truncated: boolean;
+  /** True iff the code exited 0 AND no sandbox fault fired. */
+  readonly success: boolean;
+}
+
+/** A PROGRAMMER/config error, THROWN: bad argument, illegal mount, or `kern` not installed. */
+export class SandboxError extends Error {}
+/** A requested host mount was refused as unsafe (sensitive source, or a relative/escaping path). */
+export class MountRefused extends SandboxError {}
+
+export type MountSpec = string | [target: string, mode: "ro" | "rw"];
+
+export interface SandboxOptions {
+  /** OCI image the box runs from. Default: "python:3.12-slim". */
+  image?: string;
+  /** Shell command run ONCE at open() in a NETWORK-ENABLED setup box (e.g. "pip install pandas"). */
+  setup?: string;
+  /** Host dir to persist as the workspace. Omit -> a temp dir, created on open() and deleted on close(). */
+  workspace?: string;
+  /** RAM cap in MiB (kern --memory). Default 512. null = uncapped default. */
+  memoryMb?: number | null;
+  /** CPU cap in cores (kern --cpus). null (default) = uncapped. */
+  cpus?: number | null;
+  /** Task/fork-bomb ceiling (kern --pids-limit). Default 256. */
+  pids?: number | null;
+  /** MANDATORY per-call wall-clock limit in seconds. The binding owns this deadline. Default 30. */
+  timeoutS?: number;
+  /** RELAXES ISOLATION. true shares the host network for every runCode. Default false. */
+  network?: boolean;
+  /**
+   * Restrict runCode/run to a DOMAIN ALLOWLIST instead of all-or-nothing, e.g. ["pypi.org",
+   * "files.pythonhosted.org"]. The box runs in an isolated network namespace and reaches the internet
+   * only through kern's filtering proxy, which permits just these domains. Mutually exclusive with
+   * network:true; the setup box keeps full network to install deps, the allowlist governs the run phase.
+   */
+  egressAllow?: string[];
+  /** Extra host->box binds: { hostSrc: boxTarget } or { src: [target, "ro"] }. Sensitive sources refused. */
+  mounts?: Record<string, MountSpec>;
+  /**
+   * kern resource profiles to attach, e.g. ["vcpu:heavy", "vgpio:leds", "vdisk:scratch"]. Each names a
+   * [[vcpu]]/[[vgpio]]/[[vdisk]] block in your ~/.config/kern/kern.toml: a CPU+memory slice, a specific
+   * GPIO/I2C/SPI device set (the only way to grant the box hardware), or a size-capped scratch disk.
+   * Tokens are strictly validated (prefix + alphanumeric name) so an entry can never smuggle a flag.
+   */
+  profiles?: string[];
+  /** Extra environment variables for the workload (passed via a private 0600 file, not argv). */
+  env?: Record<string, string>;
+  /** Cap on captured stdout/stderr EACH, in bytes. Default 64 MiB. */
+  maxOutputBytes?: number;
+  /** true (default) hard-enforces caps via a systemd scope (~6 ms start); false = best-effort (~3 ms). */
+  enforceLimits?: boolean;
+  /** Mount setup= deps read-only for runCode (blocks cross-run dependency poisoning). Default false. */
+  depsReadonly?: boolean;
+  /** Called with each stdout Buffer chunk as it arrives (live streaming). The full capped output is
+   * still captured in the result, so you can stream AND read result.stdout. */
+  onStdout?: (chunk: Buffer) => void;
+  /** Called with each stderr Buffer chunk as it arrives. */
+  onStderr?: (chunk: Buffer) => void;
+}
+
+export type Language = "python" | "bash" | "node";
+
+/** A configured kernel sandbox. FILE state persists across runCode/run in a workspace on disk; each
+ * call runs in a FRESH ephemeral box. Safe by default; every relaxing option says so. */
+export class Sandbox {
+  constructor(opts?: SandboxOptions);
+  /** Create/validate the workspace and run `setup`. Call before runCode/run/writeFile. */
+  open(): Promise<this>;
+  /** Delete the workspace iff we created it. Idempotent. */
+  close(): Promise<void>;
+  /** Run a snippet on the workspace in a fresh, network-off box. File state persists; memory does not. */
+  runCode(code: string, opts?: { language?: Language }): Promise<ExecutionResult>;
+  /** Run an argv ARRAY (never a shell string) in a fresh box. */
+  run(command: string[]): Promise<ExecutionResult>;
+  /** Write data to a workspace-relative path (host-direct, O_NOFOLLOW on the final component). */
+  writeFile(path: string, data: Buffer | string): Promise<void>;
+  /** Read a workspace-relative path (host-direct, O_NOFOLLOW). */
+  readFile(path: string): Promise<Buffer>;
+  /** Write a gzip tar of the whole workspace to `dest`, a portable filesystem checkpoint (NOT memory). */
+  snapshot(dest: string): void;
+  /** Extract a snapshot (from snapshot()) into the workspace, safely (rejects symlink/.. /absolute members). */
+  restore(src: string): void;
+  /** List regular files under the workspace (excludes .deps). */
+  listFiles(subdir?: string): Promise<FileInfo[]>;
+}
+
+/** Open a Sandbox, run `fn(sandbox)`, and close it even if `fn` throws. The session helper. */
+export function withSandbox<T>(fn: (sandbox: Sandbox) => Promise<T>): Promise<T>;
+export function withSandbox<T>(opts: SandboxOptions, fn: (sandbox: Sandbox) => Promise<T>): Promise<T>;
+
+/** One-shot: run `code` in a throwaway session (workspace created and deleted). */
+export function runCode(code: string, opts?: SandboxOptions & { language?: Language }): Promise<ExecutionResult>;
+
+export const version: string;

package/index.js

@@ -0,0 +1,965 @@
+/**
+ * kern-sandbox - run LLM/agent-generated code in a fast, local, daemonless kernel sandbox.
+ *
+ *   const kern = require('kern-sandbox');
+ *
+ *   // one-shot (a throwaway session under the hood)
+ *   const r = await kern.runCode("console.log(1 + 1)", { language: "node" });
+ *   console.log(r.stdout, r.success);
+ *
+ *   // a session: FILE state persists across steps; processes are ephemeral
+ *   await kern.withSandbox({ setup: "pip install pandas" }, async (sbx) => {
+ *     await sbx.writeFile("data.csv", csvBytes);
+ *     const r = await sbx.runCode("import pandas as pd; print(pd.read_csv('data.csv').shape)");
+ *     const png = await sbx.readFile("out.png");
+ *   });
+ *
+ * Design mirrors the Python binding exactly:
+ *   - FILE state persists via a workspace DIRECTORY on the host, bind-mounted into each box.
+ *     PROCESSES are ephemeral: every runCode()/run() spawns a FRESH box on that shared workspace.
+ *     In-memory state does NOT survive between calls; write to disk for continuity.
+ *   - I/O is HOST-DIRECT: single-uid maps box-root to the host user, so files the box creates are
+ *     host-owned; writeFile/readFile are plain host filesystem I/O.
+ *   - The BINDING owns the timeout (it kills the box), so a `timeout` fault is a known fact.
+ *
+ * Threat model (honest): kern is a KERNEL-BOUNDARY sandbox for YOUR OWN or SEMI-TRUSTED code. seccomp
+ * is a DENYLIST - suitable for semi-trusted agent code, NOT a hard boundary against deliberately
+ * hostile multi-tenant code (for that: a microVM / gVisor).
+ */
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+const zlib = require("zlib");
+const { spawn, spawnSync } = require("child_process");
+
+const VERSION = "0.1.1";
+
+const DEFAULT_IMAGE = "python:3.12-slim";
+const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
+const DEPS_DIR = ".deps"; // pip --target dir inside the workspace (added to PYTHONPATH for python)
+const ENV_FILE = ".kern-env"; // host-side 0600 env file (kept out of argv so values don't show in `ps`)
+const INLINE_CODE_MAX = 128 * 1024; // above this, pass code via a file instead of argv (ARG_MAX guard)
+
+// Signal-derived exit codes (128 + signum) we classify.
+const EXIT_SIGKILL = 137; // SIGKILL: timeout backstop or OOM (indistinguishable without cgroup)
+const EXIT_SIGSYS = 159; // SIGSYS: a seccomp-denied syscall = a blocked escape attempt
+const EXIT_SIGTERM = 143; // SIGTERM: kern's --timeout backstop reaping the box
+
+// Host paths a `-v` mount must never target - mounting the host's real root/config/secrets into a
+// sandbox defeats the point; the docker socket is the classic escape. Refused even when asked.
+const REFUSED_MOUNT_SOURCES = new Set([
+  "/",
+  "/etc",
+  "/root",
+  "/boot",
+  "/proc",
+  "/sys",
+  "/dev",
+  "/var/run/docker.sock",
+  "/run/docker.sock",
+]);
+
+/** A PROGRAMMER/config error, THROWN: bad argument, illegal mount, or `kern` not installed. Runtime
+ * sandbox events (timeout, blocked escape, OOM-kill) are NOT thrown - they are data in result.fault. */
+class SandboxError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SandboxError";
+  }
+}
+
+/** A requested host mount was refused as unsafe (sensitive source, or a relative/escaping path). */
+class MountRefused extends SandboxError {
+  constructor(message) {
+    super(message);
+    this.name = "MountRefused";
+  }
+}
+
+/** The outcome of one runCode()/run(). `fault` is the source of truth for "did the SANDBOX act";
+ * `exitCode`/`stdout` are what the user's code did. `success` requires both clean. */
+class ExecutionResult {
+  constructor({ stdout, stderr, exitCode, durationMs, fault, files, truncated }) {
+    this.stdout = stdout;
+    this.stderr = stderr;
+    this.exitCode = exitCode;
+    this.durationMs = durationMs;
+    /** @type {{type: string, message: string} | null} */
+    this.fault = fault || null;
+    this.files = files || [];
+    this.truncated = !!truncated;
+  }
+  /** True iff the code exited 0 AND no sandbox fault fired. */
+  get success() {
+    return this.exitCode === 0 && this.fault === null;
+  }
+}
+
+function sandboxFault(type, message) {
+  return { type, message };
+}
+
+/** Locate `kern`: $KERN_BIN if set, else the first `kern` on $PATH. */
+function findKern() {
+  const env = process.env.KERN_BIN;
+  if (env) {
+    try {
+      fs.accessSync(env, fs.constants.X_OK);
+      if (!fs.statSync(env).isFile()) throw new Error("not a file");
+    } catch {
+      throw new SandboxError(`$KERN_BIN='${env}' is not an executable file`);
+    }
+    return env;
+  }
+  const exts = [""];
+  const dirs = (process.env.PATH || "").split(path.delimiter).filter(Boolean);
+  for (const d of dirs) {
+    for (const ext of exts) {
+      const cand = path.join(d, "kern" + ext);
+      try {
+        fs.accessSync(cand, fs.constants.X_OK);
+        if (fs.statSync(cand).isFile()) return cand;
+      } catch {
+        /* keep looking */
+      }
+    }
+  }
+  throw new SandboxError(
+    "the `kern` binary was not found on PATH - install it " +
+      "(https://github.com/getkern/kern) or set $KERN_BIN",
+  );
+}
+
+/** Validate one host->box mount; refuse unsafe sources/targets. Returns [absRealSource, target]. */
+function validateMount(source, target) {
+  if (typeof target !== "string" || !target.startsWith("/"))
+    throw new MountRefused(`mount target must be an absolute path in the box, got ${JSON.stringify(target)}`);
+  if (target.split("/").some((c) => c === ".."))
+    throw new MountRefused(`mount target must not contain '..': ${JSON.stringify(target)}`);
+  const normTarget = "/" + target.split("/").filter((c) => c && c !== ".").join("/");
+  if (["/", "/proc", "/sys", "/dev"].includes(normTarget))
+    throw new MountRefused(`cannot mount over the box essential mount ${JSON.stringify(normTarget)}`);
+  if (typeof source !== "string" || !path.isAbsolute(source))
+    throw new MountRefused(`mount source must be an absolute host path, got ${JSON.stringify(source)}`);
+  let real;
+  try {
+    real = fs.realpathSync(source); // resolve symlinks BEFORE the sensitive-set check
+  } catch {
+    throw new MountRefused(`mount source does not exist: ${JSON.stringify(source)}`);
+  }
+  const home = (() => {
+    try {
+      return fs.realpathSync(os.homedir());
+    } catch {
+      return os.homedir();
+    }
+  })();
+  if (REFUSED_MOUNT_SOURCES.has(real) || real === home)
+    throw new MountRefused(
+      `refusing to mount the sensitive host path ${JSON.stringify(real)} into a sandbox ` +
+        "(this would defeat the isolation)",
+    );
+  return [real, target];
+}
+
+// A resource-profile token (`vcpu:`/`vgpio:`/`vdisk:` + a named profile from the user's kern.toml).
+// ANCHORED and charset-restricted: the token is passed as a POSITIONAL arg to `kern box`, so it must be
+// EXACTLY a known prefix plus a safe name. This is what stops a caller (or agent-chosen value) from
+// smuggling another flag through the profile list ("--net", "-v /etc:/etc", "vgpu:x", a name with a
+// space / `=` / `/` / leading dash). The three prefixes mirror `config::classify` in kern.
+const PROFILE_RE = /^(?:vcpu|vgpio|vdisk):[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** Validate one `vcpu:`/`vgpio:`/`vdisk:NAME` resource-profile token before it reaches the argv. */
+function validateProfile(token) {
+  if (typeof token !== "string" || !PROFILE_RE.test(token))
+    throw new SandboxError(
+      `invalid resource profile ${JSON.stringify(token)}: expected 'vcpu:NAME', 'vgpio:NAME' or ` +
+        "'vdisk:NAME' with an alphanumeric profile name (the profile must be defined in your kern.toml)",
+    );
+  return token;
+}
+
+// A public DNS domain for the egress allowlist. LDH labels, at least one dot (an FQDN), alphabetic TLD.
+// Restrictive on purpose: the value is comma-joined and handed to `kern box --egress-allow`, so it must
+// not carry a comma, scheme, path, port, wildcard or whitespace that could change the argument. kern
+// re-validates and SSRF-checks the resolved IPs; this is the binding's first gate.
+const DOMAIN_RE = /^(?=.{1,253}$)(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)+[A-Za-z]{2,63}$/;
+
+/** Validate one egress-allowlist domain (an FQDN like "pypi.org") before it reaches the argv. */
+function validateDomain(domain) {
+  if (typeof domain !== "string" || !DOMAIN_RE.test(domain))
+    throw new SandboxError(
+      `invalid egress domain ${JSON.stringify(domain)}: expected a bare hostname like 'pypi.org' ` +
+        "(no scheme, port, path, wildcard or spaces)",
+    );
+  return domain;
+}
+
+/** Map a Node close event {code, signal} to a unix-style rc (128 + signum for a signal). */
+function toRc(code, signal) {
+  if (typeof code === "number") return code;
+  const table = { SIGHUP: 1, SIGINT: 2, SIGKILL: 9, SIGSEGV: 11, SIGTERM: 15, SIGSYS: 31 };
+  if (signal && table[signal] !== undefined) return 128 + table[signal];
+  return -1;
+}
+
+/** True iff kern (the PARENT, before the box exists) failed to start the box. Anchored on kern's OWN
+ * diagnostic prefixes so the workload can't forge them by writing the marker to its own stderr. */
+function looksLikeStartupFailure(stderr) {
+  const markers = ["kern:", "error: pull:", "error: sandbox:", "error: box:", "error: oci:", "error: image:"];
+  for (const line of stderr.split("\n")) {
+    const s = line.replace(/^\s+/, "");
+    if (s.includes("sandbox setup failed") || markers.some((m) => s.startsWith(m))) return true;
+  }
+  return false;
+}
+
+function uniqueName() {
+  return "jssbx-" + crypto.randomBytes(6).toString("hex");
+}
+
+/** Drain a readable stream into a bounded buffer: keep at most `cap` bytes but KEEP reading past it
+ * (discarding overflow) so a flooding box never blocks on a full pipe. RAM is bounded to `cap`. */
+function cappedCollector(stream, cap, onData) {
+  const chunks = [];
+  let len = 0;
+  const state = { truncated: false };
+  stream.on("data", (chunk) => {
+    if (onData) {
+      // stream every chunk live; a callback throw must never break the drain (the box would then
+      // block on a full pipe), so swallow it, the buffered result still returns.
+      try {
+        onData(chunk);
+      } catch {
+        /* user callback error ignored on purpose */
+      }
+    }
+    if (len < cap) {
+      const room = cap - len;
+      if (chunk.length <= room) {
+        chunks.push(chunk);
+        len += chunk.length;
+      } else {
+        chunks.push(chunk.subarray(0, room));
+        len = cap;
+        state.truncated = true;
+      }
+    } else {
+      state.truncated = true;
+    }
+    // never pause: keep draining so the box can't block on a full pipe
+  });
+  stream.on("error", () => {});
+  state.buffer = () => Buffer.concat(chunks);
+  return state;
+}
+
+// --- Minimal ustar (POSIX tar) over gzip, for workspace snapshots -------------------------------
+// Dependency-free (Node's zlib does the gzip) and interoperable with `tar tzf` and the Python binding:
+// a snapshot is a real .tar.gz. Only regular files are written; on restore only files/dirs are accepted
+// (symlinks, devices, hardlinks and any absolute or `..`-escaping name are refused), and the final
+// component is opened O_NOFOLLOW, so a hostile archive can never write outside the workspace.
+
+function tarWriteFile(out, name, content) {
+  if (Buffer.byteLength(name) > 100)
+    throw new SandboxError(`snapshot: path too long for the tar format (>100 bytes): ${name}`);
+  const h = Buffer.alloc(512);
+  h.write(name, 0, 100, "utf8");
+  h.write("0000644\0", 100, 8); // mode
+  h.write("0000000\0", 108, 8); // uid
+  h.write("0000000\0", 116, 8); // gid
+  h.write(content.length.toString(8).padStart(11, "0") + "\0", 124, 12); // size (octal)
+  h.write("00000000000\0", 136, 12); // mtime 0 (deterministic)
+  h.write("        ", 148, 8); // checksum field = 8 spaces while summing
+  h.write("0", 156, 1); // typeflag '0' = regular file
+  h.write("ustar\0", 257, 6); // magic
+  h.write("00", 263, 2); // version
+  let sum = 0;
+  for (const b of h) sum += b;
+  h.write(sum.toString(8).padStart(6, "0") + "\0 ", 148, 8); // checksum: 6 octal digits, NUL, space
+  out.push(h, content);
+  const pad = (512 - (content.length % 512)) % 512;
+  if (pad) out.push(Buffer.alloc(pad));
+}
+
+function tarCollect(dir, base, skip, out) {
+  for (const entry of fs.readdirSync(dir).sort()) {
+    const abs = path.join(dir, entry);
+    const st = fs.lstatSync(abs);
+    if (st.isSymbolicLink()) continue; // never archive a symlink
+    if (st.isDirectory()) tarCollect(abs, base, skip, out);
+    else if (st.isFile()) {
+      const rel = path.relative(base, abs);
+      if (rel === skip) continue; // our private --env-file, not user state
+      tarWriteFile(out, rel.split(path.sep).join("/"), fs.readFileSync(abs));
+    }
+  }
+}
+
+function tarPack(base, skip) {
+  const out = [];
+  tarCollect(base, base, skip, out);
+  out.push(Buffer.alloc(1024)); // two zero blocks = end of archive
+  // level 1: a local checkpoint is often large or already-compressed; level 1 is several times faster
+  // than the default with a negligible size penalty. Speed over ratio here.
+  return zlib.gzipSync(Buffer.concat(out), { level: 1 });
+}
+
+function tarParse(gz) {
+  // Cap the inflated size so a tiny gzip bomb can't force a huge allocation before we even vet members.
+  const buf = zlib.gunzipSync(gz, { maxOutputLength: 1024 * 1024 * 1024 });
+  const members = [];
+  let off = 0;
+  while (off + 512 <= buf.length) {
+    const h = buf.subarray(off, off + 512);
+    if (h.every((b) => b === 0)) break; // end-of-archive zero block
+    // Verify the ustar header checksum (sum of all header bytes with the 8-byte checksum field taken as
+    // spaces): a single corrupt header field is rejected wholesale, before the per-field vetting runs.
+    const stored = parseInt(h.toString("utf8", 148, 156).replace(/\0.*$/s, "").trim(), 8);
+    let ck = 0;
+    for (let i = 0; i < 512; i++) ck += i >= 148 && i < 156 ? 0x20 : h[i];
+    if (stored !== ck) throw new SandboxError("malformed snapshot: bad header checksum");
+    // Strip a trailing slash (the ustar dir convention "d/"): otherwise path.join keeps it, and a
+    // trailing slash makes lstat FOLLOW a planted symlink ("d/" resolves the link to its target dir)
+    // instead of seeing the link, which would defeat the symlink-vet on a dir member.
+    const name = h.toString("utf8", 0, 100).replace(/\0.*$/s, "").replace(/\/+$/, "");
+    // Size is octal ASCII by spec; reject anything else rather than let parseInt guess ("12x" -> 10).
+    // This also makes a negative size impossible (no `-` in the field), closing the spin-forever case.
+    const sizeField = h.toString("utf8", 124, 136).replace(/\0.*$/s, "").trim();
+    if (!/^[0-7]*$/.test(sizeField)) throw new SandboxError("malformed snapshot: non-octal member size");
+    const size = parseInt(sizeField, 8) || 0;
+    const flag = String.fromCharCode(h[156]);
+    off += 512;
+    const type = flag === "0" || flag === "\0" ? "file" : flag === "5" ? "dir" : "other";
+    // A dir/other member carries no content in ustar; a non-zero size there is malformed, so reject it
+    // rather than silently ignore it (reject-not-guess).
+    if (type !== "file" && size !== 0)
+      throw new SandboxError("malformed snapshot: non-file member with a non-zero size");
+    // Refuse a member claiming more bytes than remain: reject the malformed archive instead of silently
+    // truncating the restored file (subarray would clamp to the buffer end).
+    if (type === "file" && off + size > buf.length)
+      throw new SandboxError("malformed snapshot: member size exceeds archive");
+    const content = type === "file" ? buf.subarray(off, off + size) : Buffer.alloc(0);
+    members.push({ name, type, content });
+    off += Math.ceil(size / 512) * 512;
+  }
+  return members;
+}
+
+class Sandbox {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.image]            OCI image the box runs from. Default a small Python image.
+   * @param {string} [opts.setup]            shell command run ONCE at open() in a NETWORK-ENABLED box.
+   * @param {string} [opts.workspace]        host dir to persist as the workspace. null -> a temp dir,
+   *                                          created on open() and DELETED on close().
+   * @param {number|null} [opts.memoryMb]    RAM cap (kern --memory). Default 512.
+   * @param {number|null} [opts.cpus]        CPU cap in cores; null = uncapped.
+   * @param {number|null} [opts.pids]        task/fork-bomb ceiling. Default 256.
+   * @param {number} [opts.timeoutS]         MANDATORY per-call wall-clock limit (binding-owned). Default 30.
+   * @param {boolean} [opts.network]         RELAXES ISOLATION. true shares the host network. Default false.
+   * @param {string[]} [opts.egressAllow]    restrict runCode/run to a DOMAIN ALLOWLIST, e.g. ["pypi.org"]; isolated netns + kern's filtering proxy. Mutually exclusive with network:true.
+   * @param {Object<string, string|[string,string]>} [opts.mounts] extra host->box binds. Sensitive refused.
+   * @param {string[]} [opts.profiles] kern resource profiles to attach, e.g. ["vcpu:heavy","vgpio:leds","vdisk:scratch"]; each names a block in your kern.toml. Strictly validated.
+   * @param {Object<string,string>} [opts.env] extra environment for the workload.
+   * @param {number} [opts.maxOutputBytes]   cap on captured stdout/stderr EACH. Default 64 MiB.
+   * @param {boolean} [opts.enforceLimits]   true (default) hard-enforces caps via a systemd scope.
+   * @param {boolean} [opts.depsReadonly]    mount setup= deps read-only for runCode (block poisoning).
+   */
+  constructor(opts = {}) {
+    this.image = opts.image ?? DEFAULT_IMAGE;
+    this.setup = opts.setup ?? null;
+    this.workspace = opts.workspace ?? null;
+    this.memoryMb = opts.memoryMb === undefined ? 512 : opts.memoryMb;
+    this.cpus = opts.cpus ?? null;
+    this.pids = opts.pids === undefined ? 256 : opts.pids;
+    this.timeoutS = opts.timeoutS ?? 30;
+    this.network = opts.network ?? false;
+    this.egressAllow = opts.egressAllow ?? null;
+    this.mounts = opts.mounts ?? null;
+    this.profiles = opts.profiles ?? null;
+    this.env = opts.env ?? null;
+    this.maxOutputBytes = opts.maxOutputBytes ?? 64 * 1024 * 1024;
+    // live output callbacks: called with each Buffer chunk as it arrives. The full capped output is
+    // still captured in the result, so you can stream AND read result.stdout.
+    this.onStdout = opts.onStdout ?? null;
+    this.onStderr = opts.onStderr ?? null;
+    this.enforceLimits = opts.enforceLimits ?? true;
+    this.depsReadonly = opts.depsReadonly ?? false;
+
+    if (!(this.timeoutS > 0)) throw new SandboxError("timeoutS must be a positive number of seconds");
+    if (!(this.maxOutputBytes > 0)) throw new SandboxError("maxOutputBytes must be positive");
+
+    this._mountArgs = [];
+    if (this.mounts) {
+      for (const [source, spec] of Object.entries(this.mounts)) {
+        let target, ro;
+        if (Array.isArray(spec)) {
+          const [t, mode] = spec;
+          if (mode !== "ro" && mode !== "rw")
+            throw new MountRefused(`mount mode must be 'ro' or 'rw', got ${JSON.stringify(mode)}`);
+          target = t;
+          ro = mode === "ro";
+        } else {
+          target = spec;
+          ro = false;
+        }
+        const [real, tgt] = validateMount(source, target);
+        this._mountArgs.push("-v", ro ? `${real}:${tgt}:ro` : `${real}:${tgt}`);
+      }
+    }
+    this._profileArgs = (this.profiles || []).map(validateProfile);
+    this._egressAllow = (this.egressAllow || []).map(validateDomain);
+    if (this._egressAllow.length && this.network)
+      throw new SandboxError(
+        "egressAllow and network:true are mutually exclusive: egressAllow gives a restricted domain " +
+          "allowlist for runCode, network:true gives the full host network",
+      );
+    this._kern = findKern();
+    this._ws = "";
+    this._ownWs = false;
+    this._entered = false;
+  }
+
+  // -- lifecycle -----------------------------------------------------------------------------------
+
+  /** Open the session: create/validate the workspace and run `setup` (if any). Must be called before
+   * runCode/run/writeFile. Prefer withSandbox() which opens and closes for you. */
+  async open() {
+    if (this._entered) return this;
+    if (this.workspace === null) {
+      this._ws = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "kern-ws-")));
+      this._ownWs = true;
+    } else {
+      validateMount(this.workspace, WORKSPACE);
+      fs.mkdirSync(this.workspace, { recursive: true });
+      this._ws = fs.realpathSync(this.workspace);
+      this._ownWs = false;
+    }
+    this._entered = true;
+    if (this.setup) await this._runSetup(this.setup);
+    return this;
+  }
+
+  /** Close the session: delete the workspace iff we created it. Idempotent. */
+  async close() {
+    if (this._ownWs && this._ws) {
+      try {
+        fs.rmSync(this._ws, { recursive: true, force: true });
+      } catch {
+        /* best-effort */
+      }
+    }
+    this._entered = false;
+  }
+
+  _requireEntered() {
+    if (!this._entered)
+      throw new SandboxError("open the Sandbox first: `await sandbox.open()` (or use withSandbox()).");
+  }
+
+  // -- the box invocation --------------------------------------------------------------------------
+
+  _baseArgv(name, { network, timeoutS, isSetup = false }) {
+    const argv = [
+      this._kern, "box", name, "--image", this.image, "--ro",
+      "-v", `${this._ws}:${WORKSPACE}`, "--workdir", WORKSPACE,
+    ];
+    if (this.depsReadonly && !isSetup) {
+      const deps = path.join(this._ws, DEPS_DIR);
+      try {
+        if (fs.statSync(deps).isDirectory()) argv.push("-v", `${deps}:${WORKSPACE}/${DEPS_DIR}:ro`);
+      } catch {
+        /* no deps yet */
+      }
+    }
+    // kern's own --timeout is a tight BACKSTOP just beyond our deadline; OUR wait is the authority.
+    argv.push("--timeout", String(timeoutS + 5));
+    if (this.memoryMb !== null) argv.push("--memory", `${this.memoryMb}m`);
+    if (this.cpus !== null) argv.push("--cpus", String(this.cpus));
+    if (this.pids !== null) argv.push("--pids-limit", String(this.pids));
+    // Network mode: egressAllow (a domain allowlist via an isolated netns + kern's filtering proxy)
+    // governs the untrusted runCode/run boxes; the setup box keeps the full network it needs to install
+    // deps. egressAllow and network are mutually exclusive (checked at construction).
+    if (this._egressAllow.length && !isSetup) argv.push("--egress-allow", this._egressAllow.join(","));
+    else if (network) argv.push("--net");
+    // Resource profiles (vcpu:/vgpio:/vdisk:NAME): positional tokens `kern box` resolves against the
+    // user's kern.toml. Validated at construction, so nothing here can be a smuggled flag.
+    argv.push(...this._profileArgs);
+    argv.push(...this._mountArgs);
+
+    const mergedEnv = { ...(this.env || {}) };
+    if (mergedEnv.PYTHONPATH === undefined) mergedEnv.PYTHONPATH = `${WORKSPACE}/${DEPS_DIR}`;
+    // Pass env via a private 0600 --env-file, NOT `--env K=V` on argv (an argv value is visible in
+    // `ps` to any local user for the box's lifetime; a credential in env= would leak).
+    if (Object.keys(mergedEnv).length > 0) {
+      const envPath = path.join(this._ws, ENV_FILE);
+      const lines = [];
+      for (const [k, v] of Object.entries(mergedEnv)) {
+        const val = String(v);
+        if (/[\n\0]/.test(k) || /[\n\0]/.test(val))
+          throw new SandboxError(`env var ${JSON.stringify(k)} must not contain a newline or NUL`);
+        lines.push(`${k}=${val}\n`);
+      }
+      // SECURITY: the box has rw access to /workspace and could plant `.kern-env` as a symlink to a host
+      // file (e.g. ~/.ssh/authorized_keys); a follow-through open would O_TRUNC-clobber it. Unlink any
+      // existing entry (removing a planted symlink) and create fresh with O_EXCL|O_NOFOLLOW so we never
+      // write through a symlink. Fails closed if a concurrent box re-plants it between the two calls.
+      try {
+        fs.unlinkSync(envPath);
+      } catch {
+        /* ENOENT is fine */
+      }
+      const fd = fs.openSync(
+        envPath,
+        fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW,
+        0o600,
+      );
+      try {
+        fs.writeSync(fd, lines.join(""));
+      } finally {
+        fs.closeSync(fd);
+      }
+      argv.push("--env-file", envPath);
+    }
+    return argv;
+  }
+
+  _spawn(command, { network, timeoutS, isSetup = false }) {
+    for (const part of command)
+      if (typeof part !== "string" || part.includes("\0"))
+        throw new SandboxError("command/code must be strings with no NUL byte");
+    const before = this._snapshot();
+    const name = uniqueName();
+    const argv = [...this._baseArgv(name, { network, timeoutS, isSetup }), "--", ...command];
+    const childEnv = { ...process.env };
+    if (!this.enforceLimits) childEnv.KERN_NO_SCOPE = "1";
+
+    const started = process.hrtime.bigint();
+    return new Promise((resolve, reject) => {
+      let child;
+      try {
+        // detached: own process group, so we can signal the box + kern as a unit (killpg).
+        child = spawn(argv[0], argv.slice(1), {
+          env: childEnv,
+          detached: true,
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+      } catch (e) {
+        return reject(new SandboxError(`could not spawn the box: ${e.message}`));
+      }
+
+      const out = cappedCollector(child.stdout, this.maxOutputBytes, this.onStdout);
+      const err = cappedCollector(child.stderr, this.maxOutputBytes, this.onStderr);
+      let timedOut = false;
+      let settled = false;
+
+      const timer = setTimeout(() => {
+        timedOut = true;
+        this._teardown(child, name, childEnv);
+      }, timeoutS * 1000);
+
+      // Hard safety net: a CPU-bound box can survive our signals until kern's backstop reaps it; never
+      // hang the caller. If close hasn't fired a few seconds after our teardown, resolve anyway.
+      let hardTimer = null;
+      const finish = (code, signal) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (hardTimer) clearTimeout(hardTimer);
+        const wallMs = Number((process.hrtime.bigint() - started) / 1000000n);
+        const stdout = out.buffer().toString("utf8");
+        const stderr = err.buffer().toString("utf8");
+        const rc = toRc(code, signal);
+        const fault = this._classify(rc, signal, stderr, timedOut);
+        const files = this._diff(before);
+        resolve(
+          new ExecutionResult({
+            stdout, stderr, exitCode: rc, durationMs: wallMs, fault, files,
+            truncated: out.truncated || err.truncated,
+          }),
+        );
+      };
+
+      child.on("error", (e) => {
+        if (e && e.code === "ENOENT")
+          return reject(new SandboxError(`could not execute kern (${argv[0]}): not found`));
+        return reject(new SandboxError(`could not execute kern: ${e.message}`));
+      });
+      child.on("close", (code, signal) => {
+        finish(code, signal);
+      });
+      // arm the hard net only once we've decided to kill (teardown sets timedOut)
+      const armHardNet = () => {
+        if (hardTimer) return;
+        hardTimer = setTimeout(() => finish(EXIT_SIGKILL, "SIGKILL"), 10000);
+      };
+      // re-check shortly after the deadline in case teardown fired
+      const watch = setInterval(() => {
+        if (settled) {
+          clearInterval(watch);
+        } else if (timedOut) {
+          clearInterval(watch);
+          armHardNet();
+        }
+      }, 250);
+    });
+  }
+
+  _teardown(child, name, childEnv) {
+    // Best-effort tear down a timed-out box. A CPU-bound box in its own PID namespace survives a plain
+    // SIGKILL of kern's parent: (1) `kern stop` (cgroup-kill); (2) SIGKILL the whole process group;
+    // (3) SIGKILL the child. kern's own --timeout backstop guarantees the box is gone shortly.
+    try {
+      spawnSync(this._kern, ["stop", name], { env: childEnv, timeout: 5000, stdio: "ignore" });
+    } catch {
+      /* ignore */
+    }
+    try {
+      if (child.pid) process.kill(-child.pid, "SIGKILL"); // process group (detached)
+    } catch {
+      /* ignore */
+    }
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      /* ignore */
+    }
+  }
+
+  _classify(rc, signal, stderr, timedOut) {
+    // ORDER IS A SECURITY PROPERTY: deterministic-by-exit-code classes are decided BEFORE the stderr
+    // heuristic, because stderr is a channel the workload controls.
+    if (timedOut)
+      return sandboxFault("timeout", `exceeded the ${this.timeoutS}s time limit (killed by the binding)`);
+    if (rc === EXIT_SIGSYS || signal === "SIGSYS")
+      return sandboxFault("escape_blocked", "a syscall was blocked by the seccomp filter (SIGSYS)");
+    if (rc === EXIT_SIGKILL || signal === "SIGKILL")
+      return sandboxFault("killed", "the box was killed (SIGKILL) - likely out of memory (exit 137)");
+    if (rc === EXIT_SIGTERM || signal === "SIGTERM")
+      return sandboxFault("timeout", "the box exceeded its time limit (reaped by kern's timeout backstop)");
+    if (rc !== 0 && looksLikeStartupFailure(stderr))
+      return sandboxFault("startup_failed", stderr.trim().slice(0, 500));
+    // Any other non-zero exit (incl. 139 SIGSEGV) is the USER's code failing - a normal Result.
+    return null;
+  }
+
+  // -- workspace file I/O (host-direct; single-uid -> box files are host-owned) ---------------------
+
+  _wsPath(rel) {
+    // Lexical containment: normalize `..`/`.`, require it stays under the workspace base. Symlinks in
+    // the final component are neutralized by O_NOFOLLOW on the actual open below.
+    const base = this._ws;
+    const full = path.normalize(path.join(base, rel));
+    if (full !== base && !full.startsWith(base + path.sep))
+      throw new SandboxError(`path escapes the workspace: ${JSON.stringify(rel)}`);
+    return full;
+  }
+
+  /** Create the parent directories of `full` under the workspace WITHOUT following a symlink in any
+   * intermediate component. `mkdir -p` follows symlinks, so a box that plants `a -> /etc` could steer a
+   * `writeFile("a/b.txt")` outside the workspace even though the final component is O_NOFOLLOW. Descend
+   * one level at a time from the (canonical) base: reject a symlink, create a missing dir non-recursively. */
+  _ensureParentDirs(full) {
+    const base = this._ws;
+    const relDir = path.relative(base, path.dirname(full));
+    if (relDir === "" || relDir === ".") return; // parent is the workspace root itself
+    let cur = base;
+    for (const part of relDir.split(path.sep)) {
+      if (!part || part === ".") continue;
+      const next = path.join(cur, part);
+      let st = null;
+      try {
+        st = fs.lstatSync(next);
+      } catch {
+        st = null;
+      }
+      if (st === null) {
+        fs.mkdirSync(next); // non-recursive: each level is a fresh real dir we just created
+      } else if (st.isSymbolicLink()) {
+        throw new SandboxError(`path escapes the workspace via a symlinked directory: ${JSON.stringify(part)}`);
+      } else if (!st.isDirectory()) {
+        throw new SandboxError(`workspace path component is not a directory: ${JSON.stringify(part)}`);
+      }
+      cur = next;
+    }
+  }
+
+  /** Write `data` (Buffer|string) to `path` (workspace-relative) - host-direct, so the box sees it next
+   * run. The final component is opened O_NOFOLLOW: a symlink the box planted can't redirect the write. */
+  async writeFile(rel, data) {
+    this._requireEntered();
+    const full = this._wsPath(rel);
+    this._ensureParentDirs(full); // symlink-safe descent, NOT mkdir -p (which follows a planted symlink)
+    const payload = Buffer.isBuffer(data) ? data : Buffer.from(String(data));
+    let fd;
+    try {
+      fd = fs.openSync(
+        full,
+        fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_NOFOLLOW,
+        0o644,
+      );
+    } catch (e) {
+      throw new SandboxError(`cannot write ${JSON.stringify(rel)}: ${e.message}`);
+    }
+    try {
+      fs.writeSync(fd, payload);
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+
+  /** Read `path` (workspace-relative) from the workspace - host-direct. Final component O_NOFOLLOW. */
+  async readFile(rel) {
+    this._requireEntered();
+    const full = this._wsPath(rel);
+    let fd;
+    try {
+      fd = fs.openSync(full, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    } catch (e) {
+      throw new SandboxError(`cannot read ${JSON.stringify(rel)}: ${e.message}`);
+    }
+    try {
+      return fs.readFileSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+
+  /** List regular files under the workspace (excluding the .deps install dir and our env file). */
+  async listFiles(subdir = "") {
+    this._requireEntered();
+    const root = subdir ? this._wsPath(subdir) : this._ws;
+    const walked = this._walk(root);
+    return Object.entries(walked).map(([p, [, size]]) => ({ path: p, size, change: "created" }));
+  }
+
+  // -- workspace snapshot (a cheap FILESYSTEM checkpoint; NOT a memory snapshot) --------------------
+
+  /** Write a gzip tar of the whole workspace to `dest` on the host, a portable filesystem checkpoint.
+   * Pair with restore() (or seed a new Sandbox({ workspace })) to resume the FILE state later or
+   * elsewhere. NOT a memory snapshot: processes are ephemeral, only on-disk state is captured. */
+  // The Node snapshot/restore path uses a HAND-ROLLED ustar parser. While it is new, it is opt-in: set
+  // KERN_SANDBOX_SNAPSHOT=1 to enable it. Fails CLOSED (refuses, never silently degrades). The Python
+  // binding uses the stdlib `tarfile` and has no such gate. Remove this once the parser is battle-tested.
+  _requireSnapshotOptIn() {
+    if (process.env.KERN_SANDBOX_SNAPSHOT !== "1")
+      throw new SandboxError(
+        "snapshot/restore is opt-in in the Node binding while its archive parser is new: " +
+          "set KERN_SANDBOX_SNAPSHOT=1 to enable it (the Python binding uses stdlib tarfile and is always on)",
+      );
+  }
+
+  snapshot(dest) {
+    this._requireEntered();
+    this._requireSnapshotOptIn();
+    fs.writeFileSync(dest, tarPack(fs.realpathSync(this._ws), ENV_FILE));
+  }
+
+  /** Extract a snapshot (from snapshot()) into the workspace, SAFELY. Every member is vetted first:
+   * absolute paths, `..` escapes and non-file/dir members (symlinks, devices, hardlinks) are refused,
+   * and each path must resolve under the workspace; the final component is opened O_NOFOLLOW. Colliding
+   * files are overwritten. */
+  restore(src) {
+    this._requireEntered();
+    this._requireSnapshotOptIn();
+    const base = fs.realpathSync(this._ws);
+    const members = tarParse(fs.readFileSync(src));
+    for (const m of members) {
+      if (m.name === "") continue;
+      if (m.name.startsWith("/") || m.name.split("/").includes(".."))
+        throw new SandboxError(`unsafe path in snapshot: ${JSON.stringify(m.name)}`);
+      if (m.type === "other")
+        throw new SandboxError(`unsafe member type in snapshot (only files/dirs): ${JSON.stringify(m.name)}`);
+      const resolved = path.resolve(base, m.name);
+      if (resolved !== base && !resolved.startsWith(base + path.sep))
+        throw new SandboxError(`snapshot member escapes the workspace: ${JSON.stringify(m.name)}`);
+    }
+    for (const m of members) {
+      if (m.name === "") continue;
+      const dest = path.join(base, m.name);
+      // _ensureParentDirs descends one level at a time and REFUSES a symlinked component, so a symlink
+      // the box planted in the workspace (e.g. `evil -> ~/.ssh`) can't steer a member outside it. A
+      // plain mkdir -p would follow that symlink (the lexical pre-vet above does not resolve it).
+      this._ensureParentDirs(dest);
+      if (m.type === "dir") {
+        let st = null;
+        try {
+          st = fs.lstatSync(dest);
+        } catch {
+          st = null;
+        }
+        if (st === null) {
+          // mkdirSync is not O_NOFOLLOW: a box could swap `dest` for a symlink between _ensureParentDirs
+          // and here (mkdir-through-symlink -> an empty dir created OUTSIDE the workspace). Node has no
+          // mkdirat, so close the race by re-lstat'ing after: a symlink swapped in is caught. No member
+          // content is ever written through it (file writes use O_NOFOLLOW leaves).
+          try {
+            fs.mkdirSync(dest);
+          } catch (e) {
+            if (e.code !== "EEXIST") throw e;
+          }
+          const post = fs.lstatSync(dest);
+          if (post.isSymbolicLink() || !post.isDirectory())
+            throw new SandboxError(`snapshot dir member is not a real directory: ${JSON.stringify(m.name)}`);
+        } else if (st.isSymbolicLink() || !st.isDirectory()) {
+          throw new SandboxError(`snapshot dir member collides with a non-directory: ${JSON.stringify(m.name)}`);
+        }
+        continue;
+      }
+      // O_NOFOLLOW: a symlink already planted at this leaf can't redirect the write outside the workspace.
+      const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_NOFOLLOW;
+      const fd = fs.openSync(dest, flags, 0o644);
+      try {
+        fs.writeSync(fd, m.content);
+      } finally {
+        fs.closeSync(fd);
+      }
+    }
+  }
+
+  // -- setup (the only network window) -------------------------------------------------------------
+
+  async _runSetup(cmd) {
+    // The network is ON only here, in a SEPARATE setup box that dies at the end. `pip install X` is
+    // routed to <workspace>/.deps; every runCode box is network-off.
+    const install = `pip install --target ${WORKSPACE}/${DEPS_DIR} --no-cache-dir --disable-pip-version-check`;
+    let shellCmd = cmd;
+    if (cmd.trim().startsWith("pip install "))
+      shellCmd = install + " " + cmd.trim().slice("pip install ".length);
+    const r = await this._spawn(["sh", "-c", shellCmd], {
+      network: true,
+      timeoutS: Math.max(this.timeoutS, 120),
+      isSetup: true,
+    });
+    if (!r.success)
+      throw new SandboxError(`setup failed (exit ${r.exitCode}): ${(r.stderr || r.stdout).trim().slice(0, 400)}`);
+  }
+
+  // -- files diff (created/modified; excludes .deps and our env file) ------------------------------
+
+  _snapshot() {
+    return this._walk(this._ws);
+  }
+
+  _walk(root) {
+    const base = this._ws;
+    const out = {};
+    const stack = [root];
+    while (stack.length) {
+      const dir = stack.pop();
+      let entries;
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const ent of entries) {
+        if (ent.isDirectory()) {
+          if (ent.name === DEPS_DIR) continue; // exclude deps from the diff
+          stack.push(path.join(dir, ent.name));
+          continue;
+        }
+        const fp = path.join(dir, ent.name);
+        let st;
+        try {
+          st = fs.lstatSync(fp);
+        } catch {
+          continue;
+        }
+        if (!st.isFile()) continue; // excludes symlinks and non-regular files
+        const rel = path.relative(base, fp);
+        if (rel === ENV_FILE) continue; // our private host-side env file, not a user artifact
+        out[rel] = [Math.round(st.mtimeMs * 1e6), st.size];
+      }
+    }
+    return out;
+  }
+
+  _diff(before) {
+    const after = this._snapshot();
+    const files = [];
+    for (const [rel, meta] of Object.entries(after)) {
+      if (!(rel in before)) files.push({ path: rel, size: meta[1], change: "created" });
+      else if (before[rel][0] !== meta[0] || before[rel][1] !== meta[1])
+        files.push({ path: rel, size: meta[1], change: "modified" });
+    }
+    return files;
+  }
+
+  // -- the two ways to run code --------------------------------------------------------------------
+
+  /** Run a snippet of `code` on the workspace in a fresh, network-off box. File state persists to the
+   * next call; in-memory state does NOT. `language` is "python" (default), "bash", or "node". Large
+   * code is written to a workspace file and run by path (no argv-size limit). */
+  async runCode(code, { language = "python" } = {}) {
+    this._requireEntered();
+    // Each runner: [binary, inline-eval-flag, file-extension]. Note node evaluates with `-e`, NOT `-c`
+    // (which is node's syntax-CHECK flag and would run nothing); python/sh use `-c`.
+    const runners = {
+      python: ["python3", "-c", "py"],
+      bash: ["sh", "-c", "sh"],
+      node: ["node", "-e", "js"],
+    };
+    const spec = runners[language];
+    if (!spec)
+      throw new SandboxError(`unsupported language ${JSON.stringify(language)} (v1: 'python' | 'bash' | 'node')`);
+    const [runner, evalFlag, ext] = spec;
+    let command;
+    if (Buffer.byteLength(code, "utf8") > INLINE_CODE_MAX) {
+      const cell = `.cell-${crypto.randomBytes(4).toString("hex")}.${ext}`;
+      await this.writeFile(cell, code);
+      command = [runner, `${WORKSPACE}/${cell}`];
+    } else {
+      command = [runner, evalFlag, code];
+    }
+    return this._spawn(command, { network: this.network, timeoutS: this.timeoutS });
+  }
+
+  /** Run an arbitrary `command` (an argv ARRAY, never a shell string) in a fresh box. */
+  async run(command) {
+    this._requireEntered();
+    if (typeof command === "string")
+      throw new SandboxError('run() takes an argv ARRAY, not a string. Use run(["sh","-c","..."]).');
+    if (!Array.isArray(command) || command.length === 0)
+      throw new SandboxError("run() needs a non-empty command array");
+    return this._spawn(command, { network: this.network, timeoutS: this.timeoutS });
+  }
+}
+
+/** Open a Sandbox, run `fn(sandbox)`, and close it (deleting a temp workspace) even if `fn` throws.
+ * The idiomatic session helper - the equivalent of Python's `with Sandbox() as s:`. */
+async function withSandbox(opts, fn) {
+  if (typeof opts === "function") {
+    fn = opts;
+    opts = {};
+  }
+  const sbx = new Sandbox(opts);
+  await sbx.open();
+  try {
+    return await fn(sbx);
+  } finally {
+    await sbx.close();
+  }
+}
+
+/** One-shot convenience: run `code` in a throwaway session (workspace created and deleted). Equivalent
+ * to `withSandbox(opts, s => s.runCode(code, {language}))`. For multi-step work, use withSandbox(). */
+async function runCode(code, opts = {}) {
+  const { language = "python", ...rest } = opts;
+  return withSandbox(rest, (s) => s.runCode(code, { language }));
+}
+
+module.exports = {
+  Sandbox,
+  withSandbox,
+  runCode,
+  ExecutionResult,
+  SandboxError,
+  MountRefused,
+  version: VERSION,
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "kern-sandbox",
+  "version": "0.1.1",
+  "description": "Run LLM/agent-generated code in a fast, local, daemonless kernel sandbox. A thin, dependency-free wrapper around the kern binary.",
+  "keywords": [
+    "sandbox",
+    "kern",
+    "agent",
+    "llm",
+    "code-execution",
+    "isolation",
+    "seccomp",
+    "container",
+    "e2b"
+  ],
+  "homepage": "https://github.com/getkern/kern/tree/main/bindings/node",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/getkern/kern.git",
+    "directory": "bindings/node"
+  },
+  "bugs": {
+    "url": "https://github.com/getkern/kern/issues"
+  },
+  "license": "Apache-2.0",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {},
+  "os": [
+    "linux"
+  ]
+}