kern-sandbox 0.2.23 → 0.2.24

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 });
@@ -228,7 +228,7 @@ password. The same connect is refused under the default `network: false`, and `e
 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.24";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
@@ -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.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.",
   "keywords": [
     "sandbox",