kern-sandbox 0.1.36 → 0.1.38

package/README.md

@@ -249,6 +249,63 @@ explicit flags that **override** a profile's values (and the `memoryMb` default
 `memory`, so pass `memoryMb: null` to let the profile apply). The **MCP server** (`kern-mcp`, for Claude
 Desktop / Cursor) ships in the Python package `kern-sandbox` (`pip install kern-sandbox`).
 
+## Egress: the setting between no network and the host's
+
+`network: false` gives the run phase no network and `network: true` gives it the host's. `egressAllow`
+is the middle one, and usually the one an agent wants:
+
+```js
+await 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
+proxy, which permits those domains and nothing else: a workload can fetch from an index you chose and
+cannot exfiltrate elsewhere. Mutually exclusive with `network: true`. The `setup` box keeps full
+network to install dependencies; the allowlist governs the run phase, which is the one executing code
+you did not read.
+
+`kernel()` returns a `Kernel`, and a refused mount throws `MountRefused` rather than the generic
+`SandboxError`, so a caller can tell "this sandbox will not do that" from "the sandbox broke".
+`DEFAULT_TMPFS_MB` and `version` are exported for callers that assert on them.
+
+## Prewarming: a box ready before the call arrives
+
+`prewarm: N` keeps N boxes started in advance, each holding a booted interpreter that has run nothing,
+so a `runCode` claims one instead of paying for a box start plus an interpreter boot. Measured on
+`python:3.12-slim`, six calls each: **14.2 ms p50 by default against 0.8 ms with `prewarm: 4`**, and
+30.9 ms against 0.9 for the first call.
+
+The refill runs while your agent thinks, so it is off the caller's clock. That also says when it buys
+nothing: if calls arrive faster than the pool refills, the pool empties and you are back to the
+default cost. N is the burst you want covered, not a throughput knob.
+
+Each prewarmed box serves ONE call and is discarded, so the isolation is unchanged: a fresh box per
+call, network off, the same caps. Only the moment of creation moves. That is the difference from
+`kernel()`, which deliberately shares one process across cells.
+
+```js
+await withSandbox({ image: "python:3.12-slim", prewarm: 4 }, async (sbx) => {
+  const r = await sbx.runCode("print(1)");   // served from the pool
+});
+```
+
+The pool key includes the image, the caps and the profiles, so a session with different settings never
+receives a box built for another one.
+
+## Run pi's coding tools in a box
+
+[`integrations/pi`](https://github.com/getkern/kern/tree/main/integrations/pi) is an extension for
+[pi](https://github.com/earendil-works/pi) built on THIS binding: it routes pi's built-in `bash`,
+`read`, `write`, `edit`, `ls`, `grep` and `find` tools into a kern box. The working directory is
+mounted at `/workspace`, so edits write through to the host and everything else a command touches dies
+with the box. pi's default posture is no sandbox: it runs as the user who launched it.
+
+The two halves are not confined by the same thing, and the extension's README says which is which:
+`bash` runs INSIDE the box (namespaces, seccomp allowlist, cgroup caps), while `read` and the staging
+half of `write` are host filesystem calls guarded by this binding's `O_NOFOLLOW` and its
+`/proc/self/fd` containment check. Needs Linux, the `kern` binary, and **Node 22 or newer**: pi's own
+package manager imports `globSync` from `node:fs`, which landed in 22.
+
 ## Charts, rich results, live output, and checkpoints
 
 **Rich results (the "code interpreter" pattern).** `runCode` runs Python by default, and like a

package/index.js

@@ -36,7 +36,7 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const { spawn, spawnSync } = require("child_process");
 
-const VERSION = "0.1.36";
+const VERSION = "0.1.38";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kern-sandbox",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "kern is a fast, rootless sandbox and virtual resource runtime for any workload, including untrusted and AI-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",
@@ -38,9 +38,6 @@
   "scripts": {
     "test": "node --test"
   },
-  "dependencies": {
-    "kern-sandbox": "file:../../../../../../tmp/kern-sandbox-0.1.36.tgz"
-  },
   "os": [
     "linux"
   ]