kern-sandbox 0.1.35 → 0.1.37

package/README.md

@@ -28,7 +28,11 @@ const r = await kern.runCode("print(sum(range(100)))");
 console.log(r.stdout, r.success); // "4950\n" true
 ```
 
-TypeScript types ship in the box:
+TypeScript types ship in the box. `Buffer` appears in the public surface **because we typed it that
+way**, so a TypeScript consumer also needs `@types/node`; without it `tsc` reports `Cannot find name
+'Buffer'` against this package's `.d.ts` and tells you what to install. Typing that surface as
+`Uint8Array` would remove the requirement (a `Buffer` is one), and that is a change to the published
+surface rather than a fix, so it is not in this release.
 
 ```ts
 import { runCode, withSandbox, Sandbox } from "kern-sandbox";
@@ -93,7 +97,10 @@ const r = await kern.runCode("console.log([1,2,3].map(x => x * x))", {
 });
 ```
 
-`language` is `"python"` (default), `"bash"`, or `"node"`. Match the image to the language.
+`language` is `"python"` (default), `"bash"`, `"sh"` or `"node"`. Match the image to the language:
+**`bash` runs bash and `sh` runs the POSIX shell**, which are different languages (`[[ ]]`, arrays and
+`pipefail` are bash), and alpine carries no bash at all. Asking for one the image lacks returns an
+`exec_failed` fault naming it, never a different shell.
 
 ## The result
 
@@ -178,6 +185,7 @@ new Sandbox({
                    // user namespace. Pass [] to keep them (needed only if the workload binds a
                    // port below 1024 INSIDE the box).
   mounts,          // { hostSrc: boxTarget } or { src: [target, "ro"] }
+  tmpfs,           // omitted -> 64 MiB of scratch at /tmp; {} -> none; { "/tmp": "512m" } to resize
   profiles,        // reusable kern.toml profiles: ["vcpu:heavy", "vgpio:leds", "vdisk:scratch"]
   env,             // { KEY: "value" }
   maxOutputBytes,  // default 64 MiB
@@ -187,19 +195,98 @@ new Sandbox({
                    // apparmor=), an LSM layer over seccomp; kern fails the box CLOSED if it isn't loaded.
   requireLimits,   // default false; true = FAIL-CLOSED (refuse to start unless caps enforced). NOT
                    // enforceLimits (that picks the cap PATH); mutually exclusive with KERN_ALLOW_UNCAPPED env.
-  depsReadonly,    // default false
+  depsReadonly,    // default TRUE: runCode cannot modify what setup= installed
   trackFiles,      // default true: diff the workspace each call for result.files (O(files)); false = [], O(1)
   onStdout,        // (chunk: Buffer) => void, live stdout streaming (result.stdout still captured)
   onStderr,        // (chunk: Buffer) => void, live stderr streaming
 });
 ```
 
+**Writable paths: `/workspace`, `/tmp` and `/dev/shm`.** The box root is read-only, so `/tmp` is a
+64 MiB tmpfs this binding mounts for you. Without it a write naming `/tmp` fails with `EROFS` and
+temp-file helpers fall back to the current directory, quietly putting scratch into your persistent
+workspace where `listFiles` then reports it. The bytes are charged to the box's own memory cgroup, so
+filling `/tmp` OOM-kills the box and never fills the host disk. Resize with `tmpfs: { "/tmp": "512m" }`,
+remove with `tmpfs: {}`, or bind your own directory at `/tmp` through `mounts` and the default steps
+aside (a `:ro` bind included, which leaves `/tmp` read-only: your call, not an accident). **The unit is
+required and the target may not contain a `:`.** kern's CLI takes both spellings and means the
+opposite of what you do: a bare `"64"` is 64 BYTES, `"0"` is UNLIMITED, and `["/scratch:9g"]` mounts
+`/scratch` at 9 GiB rather than a directory by that name. All three measured, all three refused here. A size larger than `memoryMb` is refused for the same family
+of reason: `df` would report it to a program that preflights. The binding's own default is clamped to
+half the cap instead.
+
+**`memoryMb` bounds the cgroup, not the workload's usable memory.** The cap is shared with
+memory-backed filesystems in the same box, and `/dev/shm` is one of them with **no size at all** (the
+kernel's tmpfs default, half of host RAM, so it scales with the machine and not with your config).
+Measured: 200 MiB written there under `memoryMb: 128` OOM-kills the box whatever `/tmp` is set to.
+`tmpfs: { "/dev/shm": ... }` is refused by kern; `mounts` at the same target IS accepted and stacks over
+kern's own mount; measured through it, `multiprocessing.shared_memory` and POSIX semaphores still
+work. Two costs: a plain directory is unbounded on DISK instead of in RAM, so bounding it means
+binding a host directory that is itself a sized tmpfs, and it has no tmpfs lifetime, so what the box
+writes to `/dev/shm` is still on the host after the box dies.
+
+**Scratch does not survive a call.** Each `runCode` is a fresh box, so `/tmp` is fresh too while the
+workspace persists. Put anything a later call must find in the workspace. The `setup` box is the exception: an install needs unbounded scratch, so the default is not
+applied there (an explicit `tmpfs` still is).
+
+**Toolchains in the box** need two writable places, and the error names neither. Go reports `failed to
+initialize build cache at /root/.cache`, which says nothing about `HOME`; npm renders a failed
+`mkdir /root/.npm` as `Invalid response body while trying to fetch https://registry.npmjs.org/...`,
+which reads as a network fault and is not one. Measured on `node:22`: neither -> exit 2, `HOME` alone
+with a read-only `/tmp` -> still exit 2, both -> exit 0. Pass both:
+
+```js
+new Sandbox({
+  image: "golang:1.23-alpine",
+  env: { HOME: "/workspace" },   // npm's ~/.npm, Go's ~/.cache, Rust's CARGO_HOME, .NET's NuGet
+  tmpfs: { "/tmp": "512m" },     // scratch; 64 MiB fits a small install, a real one needs more
+});
+```
+
 `runCode`/`run` also take `timeoutS`/`onStdout`/`onStderr` as **per-call** options that override the
 session defaults for that one call. A `vcpu:` profile can carry `cpus`+`memory`; `memoryMb`/`cpus` are
 explicit flags that **override** a profile's values (and the `memoryMb` default `512` shadows a profile's
 `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`).
 
+## 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.d.ts

@@ -1,5 +1,20 @@
 // Type definitions for kern-sandbox
 // Run LLM/agent-generated code in a fast, local, daemonless kernel sandbox.
+//
+// `Buffer` is in this file's public surface (chunk callbacks, readFile, decoded images), so a
+// TypeScript consumer needs `@types/node`. Deliberately NOT declared with a
+// `/// <reference types="node" />`: that was tried and measured, and it made things worse. Without
+// Node's types the reference adds `TS2688: Cannot find type definition file for 'node'` on TOP of the
+// six `Buffer` errors, and those six already carry TypeScript's own remedy, verbatim: "Do you need to
+// install type definitions for node? Try `npm i --save-dev @types/node`". Seven errors that name the
+// fix are not better than six that name it. The README says it in prose instead.
+//
+// There is a THIRD option, and it is a decision rather than a fix, so it is written down and not
+// taken on a delivery day: type this surface as `Uint8Array` instead of `Buffer`. `Buffer extends
+// Uint8Array`, so a caller's Buffers still satisfy it, the package stops needing `@types/node` at
+// all, and it becomes typable outside Node. That is a change to the published surface, which is a
+// 0.2 conversation. Until then the requirement is a consequence of a type choice we made, not a
+// law of the platform, and the README should not imply otherwise.
 
 /** What stopped the code at the SANDBOX level. Reported as data on a result, never thrown. */
 export type SandboxFaultType = "timeout" | "oom" | "escape_blocked" | "killed" | "startup_failed" | "exec_failed";
@@ -93,6 +108,31 @@ export interface SandboxOptions {
   egressAllow?: string[];
   /** Extra host->box binds: { hostSrc: boxTarget } or { src: [target, "ro"] }. Sensitive sources refused. */
   mounts?: Record<string, MountSpec>;
+  /**
+   * Fresh in-box scratch filesystems (kern `--tmpfs`), as `{ "/path": "64m" }` or `["/path"]`.
+   *
+   * **A 64 MiB tmpfs is mounted at `/tmp` by default.** The box root is read-only, so without it a
+   * write naming `/tmp` fails and temp-file helpers fall back to the current directory, quietly
+   * putting scratch into your persistent workspace. Pass `{ "/tmp": "512m" }` to resize, `{}` for
+   * none, or bind your own directory at `/tmp` through `mounts` and the default steps aside. The
+   * bytes are charged to the box's memory cgroup, so a runaway writer is OOM-killed rather than
+   * filling the host disk.
+   *
+   * **Scratch does not survive a command, EXCEPT in a kernel().** Each `runCode`/`run` is a fresh
+   * box, so the tmpfs is fresh too, while the workspace persists. A `kernel()` is one long-lived box,
+   * so its `/tmp` persists across cells and the size is CUMULATIVE: measured at 10 MiB per step under
+   * the 64 MiB default, ten `runCode` calls all pass while the same ten cells in a kernel fail from
+   * the seventh with ENOSPC.
+   *
+   * A read-only `/tmp` used to fail LOUDLY at the moment of the mistake; now a tool that writes state
+   * to the workspace and a lock to `/tmp` writes both, and the next call finds workspace state
+   * pointing at a `/tmp` path that is gone. Put anything another call has to find in the workspace.
+   *
+   * The EFFECTIVE ceiling is `min(size, memoryMb)`, and `df` inside the box
+   * does not know that: a `"1t"` scratch shows 1.0T free and the first write past the cap is an OOM,
+   * not `ENOSPC`. The `oom` fault names the scratch so the reader is not sent to their allocation.
+   */
+  tmpfs?: Record<string, string | null> | string[];
   /**
    * kern resource profiles to attach, e.g. ["vcpu:heavy", "vgpio:leds", "vdisk:scratch"]. Each names a
    * [[vcpu]]/[[vgpio]]/[[vdisk]] block in your ~/.config/kern/kern.toml: a CPU+memory slice, a specific
@@ -116,9 +156,24 @@ export interface SandboxOptions {
   onStdout?: (chunk: Buffer) => void;
   /** Called with each stderr Buffer chunk as it arrives. */
   onStderr?: (chunk: Buffer) => void;
+  /** Keep N boxes started in advance, each holding a booted interpreter that has run nothing, so a
+   * python `runCode` claims one instead of starting its own: ~41 ms per call becomes ~2 ms.
+   *
+   * It does NOT change what a call gets. Each prewarmed box serves exactly one cell and is then
+   * destroyed, so the cell still runs in a private box that has executed nothing else; what moves is
+   * when the box and interpreter started. A call that streams (`onStdout`/`onStderr`), asks for a
+   * non-python language, or differs in posture from the pooled box takes the ordinary path.
+   *
+   * Default 0: N warm boxes hold N booted interpreters for the life of the session whether or not a
+   * call arrives, which is a resource decision the caller owns. A slot refills in ~70 ms, so N is a
+   * burst budget - N back-to-back calls run warm and the rest fall back until the pool catches up. */
+  prewarm?: number;
 }
 
-export type Language = "python" | "bash" | "node";
+/** `bash` runs bash and `sh` runs the POSIX shell: they are different shells, and the image must
+ * provide the one you ask for. On alpine there is no bash, and asking for it yields an
+ * `exec_failed` fault naming it rather than a shell you did not choose. */
+export type Language = "python" | "bash" | "sh" | "node";
 
 /** Per-call overrides for runCode()/run(): each defaults to the Sandbox's constructor value; an explicit
  * value applies to this call only (a `null` callback disables streaming for the call). */
@@ -148,6 +203,15 @@ export class Sandbox {
   /** Write data to a workspace-relative path (host-direct, O_NOFOLLOW on the final component). */
   writeFile(path: string, data: Buffer | string): Promise<void>;
   /** Read a workspace-relative path (host-direct, O_NOFOLLOW). */
+  /**
+   * Read a workspace file, host-direct, every path component opened `O_NOFOLLOW`.
+   *
+   * `maxBytes` is a **REFUSAL threshold, not a partial read**: a larger file throws and nothing is
+   * returned, it never yields the first `maxBytes` bytes. Safer for a boundary (a silent truncation is
+   * how a caller ends up parsing half a file) and not what the name suggests, which is why it is
+   * spelled out: asking for 16 bytes to sniff a magic number and wrapping the call in `catch` turns
+   * every image in a project into "not an image", in silence.
+   */
   readFile(path: string, opts?: { maxBytes?: number }): Promise<Buffer>;
   /** Write a gzip tar of the whole workspace to `dest`, a portable filesystem checkpoint (NOT memory). */
   snapshot(dest: string): void;
@@ -184,3 +248,10 @@ export function withSandbox<T>(opts: SandboxOptions, fn: (sandbox: Sandbox) => P
 export function runCode(code: string, opts?: SandboxOptions & { language?: Language }): Promise<ExecutionResult>;
 
 export const version: string;
+
+/** The size, in MiB, of the tmpfs this binding mounts at `/tmp` by default.
+ *
+ * Exported so a consumer that wants a different default can express it as a multiple of this one
+ * rather than declaring a second independent number that drifts from it.
+ */
+export const DEFAULT_TMPFS_MB: number;