kern-sandbox 0.2.25 → 0.2.27

package/README.md

@@ -4,7 +4,7 @@
 
 Fast means milliseconds, and it is two numbers rather than one: the box is the cheap part, and an
 interpreter starting inside it costs more than the box does. Both depend on your machine, so they are
-measured under [Prewarming](#prewarming-a-box-ready-before-the-call-arrives) with the machine and the method beside them, and the
+measured under [Prewarming](https://github.com/getkern/kern/blob/main/bindings/node/README.md#prewarming-a-box-ready-before-the-call-arrives) with the machine and the method beside them, and the
 runtime's own are in [BENCHMARKS.md](https://github.com/getkern/kern/blob/main/BENCHMARKS.md).
 
 `kern-sandbox` is the Node and TypeScript binding for **[kern](https://getkern.dev)**: a rootless,
@@ -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
@@ -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.25";
+const VERSION = "0.2.27";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kern-sandbox",
-  "version": "0.2.25",
-  "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.27",
+  "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",