kern-sandbox 0.2.23 → 0.2.25

package/README.md

@@ -140,7 +140,7 @@ A non-zero exit from *your code* is **not** a fault (`fault` stays `null`): it i
 | `oom` | the kernel's OOM killer took the box against its own memory cap. Read from a descriptor the code in the box cannot write, so it is an observation and not a guess from the exit code |
 | `killed` | SIGKILL with **no** OOM reported: an external kill (`kern stop`, a signal, the host out of memory), or a cap that did not bind here, which the message names |
 | `exec_failed` | the box started, the command did not exist inside it. `{language:"node"}` on an image with no `node` is the ordinary way there; the message names the binary AND the image |
-| `startup_failed` | the box never ran, and kern said why in `stderr`. Two shapes: your `timeoutS` fired while kern was still BUILDING the box (run it again: a fast second call was a cold image read), or kern refused to build it at all (an image that cannot be pulled, a mount it will not make) |
+| `startup_failed` | the box never ran, and kern said why in `stderr`. Two shapes: your `timeoutS` fired while kern was still BUILDING the box (run it again: if the second call is fast it was a cold image read, and if it is not, look for a bind source on a dead NFS export), or kern refused to build it at all (an image that cannot be pulled, a mount it will not make). The cold read is the FIRST call on a new machine and it is not small: 38 s for an arm64 image on a Raspberry Pi 5 here, against 0.1 s warm |
 
 ```js
 const r = await kern.runCode("while True: pass", { timeoutS: 5 });
@@ -222,13 +222,13 @@ 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.
 
 ```js
-await withSandbox({ egressAllow: ["pypi.org", "files.pythonhosted.org"] }, async (sbx) => { /* ... */ });
+await kern.withSandbox({ egressAllow: ["pypi.org", "files.pythonhosted.org"] }, async (sbx) => { /* ... */ });
 ```
 
 The box stays in its own network namespace and reaches the internet only through kern's filtering
@@ -293,7 +293,7 @@ bare expression**, every **`display(obj)`**, and **every open matplotlib figure
 no `savefig`. Accessors: `.png`, `.jpeg`, `.html`, `.svg`, `.markdown`, `.json`, `.text`.
 
 ```js
-await withSandbox({ setup: "pip install pandas matplotlib" }, async (sbx) => {
+await kern.withSandbox({ setup: "pip install pandas matplotlib" }, async (sbx) => {
   await sbx.writeFile("data.csv", "a,b\n1,2\n3,4\n");
   const r = await sbx.runCode("import pandas as pd; pd.read_csv('data.csv').describe()");
   r.results[0].html;                       // the DataFrame as an HTML table
@@ -317,6 +317,32 @@ gVisor. The wider denylist is the opt-out (`KERN_SECCOMP=denylist`), and `securi
 bundles the allowlist with `--cap-drop ALL` + `--read-only`. See the project's
 [SECURITY.md](https://github.com/getkern/kern/blob/main/SECURITY.md).
 
+**Two jobs, and the handoff is the point.** A microVM product (Docker Sandboxes, Firecracker, Kata,
+gVisor) gives the code a kernel of its own, and that is the right answer when the code is actively
+hostile or belongs to someone else. It costs what a machine costs: measured here against `sbx`
+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.
+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
+them where it can, but the box still reads the HOST's numbers for things nothing charges it for:
+`df` on the workspace reports the host's filesystem, because that is what it is, a bind mount with
+no quota, and `nproc` reports the host's core count even under a `cpus` cap, which caps TIME and not
+the count (measured here: 28 inside a box capped at 0.5 cores, 28 outside). Anything that sizes
+itself from a cgroup-unaware API is in the same family: Go's `GOMAXPROCS`, some JVMs, `ray`-style
+CPU detection. `memoryMb` and `pids` ARE enforced and visible as limits, but ONLY where the host
+gives kern a delegated cgroup: on one that does not (a root shell with no user manager, some CI
+runners) kern warns and the box runs UNCAPPED. `kern doctor` says which path a host takes, and
+`requireLimits: true` refuses to start rather than run a box whose caps are decoration.
+
+**`npm install kern-sandbox` does not install the sandbox.** The binding drives a `kern` binary it
+finds on `PATH` or in `$KERN_BIN`, and that is a SECOND thing to install and to keep current: a
+binary that is not kern is refused by name, but an OLDER kern runs fine and answers fewer questions,
+because the fault taxonomy reads bytes only newer builds write. If a verdict looks wrong, print
+`kern --version` before anything else.
+
 ## License
 
 [Apache-2.0](https://github.com/getkern/kern/blob/main/LICENSE).

package/index.d.ts

@@ -71,6 +71,12 @@ export class ExecutionResult {
   results: Result[];
   /** True iff the code exited 0 AND no sandbox fault fired. */
   readonly success: boolean;
+  /** `stderr` with kern's own `note:`/`warning:` lines removed: what the CODE wrote. Feed this to a
+   * model, not `stderr`, or kern's diagnostics read as the workload's. */
+  readonly codeStderr: string;
+  /** The complement of `codeStderr`: the lines kern wrote about itself, one per entry. `stderr`
+   * still holds both, in order. */
+  readonly runtimeNotes: string[];
 }
 
 /** A PROGRAMMER/config error, THROWN: bad argument, illegal mount, or `kern` not installed. */

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.23";
+const VERSION = "0.2.25";
 
 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)
@@ -1972,6 +1972,17 @@ class Sandbox {
   // -- workspace file I/O (host-direct; single-uid -> box files are host-owned) ---------------------
 
   _wsPath(rel) {
+    // A NUL BYTE IS REFUSED HERE, in the same words Python uses. Without it, node's own check fires
+    // deeper and the caller reads "The argument 'path' must be a string, Uint8Array...", which names
+    // the argument's TYPE for a path that is a perfectly good string. Found through the Python MCP
+    // server, where the same input surfaced as `internal error: ValueError`; both bindings answer the
+    // question that was asked now.
+    if (typeof rel === "string" && rel.includes("\u0000")) {
+      throw new SandboxError(
+        `path contains a NUL byte: ${JSON.stringify(rel)}. A NUL terminates a path for every API ` +
+          `below this one, so the name cannot mean what it appears to say`,
+      );
+    }
     // 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.
     //

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kern-sandbox",
-  "version": "0.2.23",
+  "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.",
   "keywords": [
     "sandbox",