kern-sandbox 0.2.24 → 0.2.26

package/README.md

@@ -12,10 +12,17 @@ kernel-enforced sandbox out of one static binary, with no daemon, no VM and no c
 tool-call, a model's generated snippet, a CI step: code that runs before anyone reads it gets its own
 box, and the box is thrown away after.
 
-Network off, memory and PID caps the kernel enforces, capabilities dropped, a deny-by-default seccomp
-allowlist, and a wall-clock deadline the binding applies from **outside** the box, so code that hangs
-cannot outlive it. Dependency-free: it shells out to the `kern` binary and does not re-implement
-isolation in JavaScript.
+Network off, memory and PID caps the kernel enforces **where your host delegates them**,
+capabilities dropped, a deny-by-default seccomp allowlist, and a wall-clock deadline the binding
+applies from **outside** the box, so code that hangs cannot outlive it. Whether the caps bind is a property of your
+HOST, not of kern: they need a delegated cgroup, which a desktop session has and a bare root shell
+in a container often does not. `kern doctor` says which you have, and `requireLimits: true` makes an
+unenforceable cap FATAL: the box refuses to start rather than run uncapped. It arrives the way every
+other refusal does, as `fault.type === "startup_failed"` on the result, NOT as an exception from the
+constructor, so a caller that only catches exceptions will walk past it.
+
+Dependency-free: it shells out to the `kern` binary and does not re-implement isolation in
+JavaScript.
 
 **Your loop reads a field, not a stack trace.** A timeout, an OOM-kill, a blocked syscall or a missing
 interpreter each arrive as a typed `fault` on the result, beside stdout and the exit code, so the
@@ -222,7 +229,7 @@ is the middle one, and usually the one an agent wants:
 
 **`network: true` includes the host's LOOPBACK, which is where unauthenticated services live.** It
 puts the box in the host's network namespace, so `127.0.0.1` inside the box is the host's
-`127.0.0.1`: a reviewer's cell connected to `127.0.0.1:22` and read back `SSH-2.0-OpenSSH_9.6p1`,
+`127.0.0.1`: a test's cell connected to `127.0.0.1:22` and read back `SSH-2.0-OpenSSH_9.6p1`,
 and a developer's laptop is where a database, a Redis and a dashboard sit bound to localhost with no
 password. The same connect is refused under the default `network: false`, and `egressAllow` refuses
 it too, because that one goes through kern's proxy rather than through the host's stack.
@@ -254,11 +261,16 @@ or Redis connection under `egressAllow` cannot resolve its host. For a database,
 `prewarm: N` keeps N boxes started in advance, each holding a booted interpreter that has run nothing,
 and refills in the background while your agent thinks. Measured on `python:3.12-slim`:
 
-| | first call | p50 within the burst |
+| `runCode` | first call | p50 within the burst |
 |---|---:|---:|
 | default | 30.9 ms | 14.2 ms |
 | `prewarm: 4` | 0.9 ms | **0.8 ms** |
 
+**The number is `runCode`, not `run()`.** A prewarmed box holds a BOOTED INTERPRETER, so what the
+pool removes is the interpreter's cost and not the box's. `run(["true"])` starts a fresh box either
+way and reads the same either way: measured, 4.74 ms with the pool against 4.67 ms without it. Time
+the wrong call and prewarming looks like a no-op.
+
 **The pool covers a burst, not a rate**, and it refills in the background: past N the cost returns to
 the default, and a call made immediately after construction pays the default until the boxes exist.
 
@@ -323,7 +335,8 @@ hostile or belongs to someone else. It costs what a machine costs: measured here
 0.43.0 on the same laptop, half a second per command in a live sandbox and about three seconds to
 create one, against 2 ms and 4 ms for kern, with `uname -r` inside reading its own kernel there and
 the host's here. kern is for the OTHER job, the one an agent loop does a thousand times: a cell per
-call, network off, memory and pids the kernel enforces, a deadline applied from outside the box.
+call, network off, memory and pids the kernel enforces where the host delegates them, a
+deadline applied from outside the box.
 Pick by which job you have, not by the ratio.
 
 **What the box does NOT hide from the code inside it.** The caps are real and the kernel enforces

package/index.js

@@ -36,7 +36,7 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const { spawn, spawnSync } = require("child_process");
 
-const VERSION = "0.2.24";
+const VERSION = "0.2.26";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
@@ -458,12 +458,12 @@ function kernStateDirs() {
   const uid = process.getuid();
   const home = os.homedir();
   // EACH DIRECTORY TWICE: where the environment says it is, AND where XDG says it is by default. The
-  // runtime dir was already spelled both ways; the other three were not, and a reviewer measured the
+  // runtime dir was already spelled both ways; the other three were not, and an independent test measured the
   // consequence in one process - with `XDG_DATA_HOME=/tmp/xdh2`, `~/.local/share/kern` was ACCEPTED
   // and still held `builds` and `volumes`. The variable answers "which kern will this SDK spawn",
   // which is the right input for the guard, but data a previous run left on disk does not move with it.
   //
-  // The DATA dir itself joined the list after the same reviewer took the refused two as the shape of
+  // The DATA dir itself joined the list after the same independent test took the refused two as the shape of
   // the rule and looked for the rest: it holds `volumes/`, the CONTENT of every named volume on this
   // host, and `builds/`, the records a later image is assembled from.
   const known = [
@@ -641,7 +641,7 @@ const VERIFIED_KERN = new Set();
 
 /** Refuse a binary that does not IDENTIFY ITSELF as kern. Throws `SandboxError` if it does not.
  *
- * MEASURED, and found by an external reviewer running the positive control this project wrote for him:
+ * MEASURED, and found by an independent test running the positive control this project wrote for him:
  * with `KERN_BIN=/bin/true` a call returned `success: true, exitCode: 0, fault: null` and an empty
  * stdout. The code never ran and the caller was told it had. Any `kern` earlier in `PATH` that is not
  * kern does this: a leftover wrapper, a shim, a no-op. An agent loop reads `success` and every
@@ -1130,7 +1130,7 @@ function kernReportedOom(stderr) {
  *
  * WHAT THIS REPLACED: a list of eleven message OPENINGS, each added after a caller measured a
  * `fault: null`. Enumerating the error texts of a binary with hundreds of them behind one printer cannot
- * be finished, and an external reviewer ended the argument with `image: ""`, whose
+ * be finished, and an independent test ended the argument with `image: ""`, whose
  * `error: bad image reference: empty` was in none of the eleven. */
 const KERN_SPEAKING = ["error: ", "kern:"];
 
@@ -1569,7 +1569,7 @@ class Sandbox {
    * that will never exist would both litter the workspace and collide with itself. A dry argv is for
    * COMPARING, never for running. */
   _baseArgv(name, { network, timeoutS, isSetup = false, dry = false }) {
-    // IDENTITY IS RE-ASSERTED PER BOX, not once per Sandbox, and an external reviewer is the reason. He
+    // IDENTITY IS RE-ASSERTED PER BOX, not once per Sandbox, and an independent test is the reason. He
     // overwrote the verified binary IN PLACE with `/bin/true` while a Sandbox was open: the next call
     // correctly refused to call an empty run a success, and the message it refused with quoted the
     // version from the FIRST verification - stating that a file which now prints `true (GNU coreutils)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kern-sandbox",
-  "version": "0.2.24",
-  "description": "kern is a fast, rootless sandbox and virtual resource runtime for any workload, including untrusted and LLM-generated code; kern-sandbox is its Node/TypeScript binding. Run untrusted or agent-generated code (Python/JS/Bash) in a real, kernel-enforced box in single-digit milliseconds, with no cloud, no account and no VM.",
+  "version": "0.2.26",
+  "description": "kern is a fast, rootless sandbox and virtual resource runtime for any workload, including untrusted and LLM-generated code; kern-sandbox is its Node/TypeScript binding. Run untrusted or agent-generated code (Python/JS/Bash) in a real, kernel-enforced box, one per call, with no cloud, no account and no VM.",
   "keywords": [
     "sandbox",
     "kern",