kern-sandbox 0.1.0__tar.gz

kern_sandbox-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+.kern-env
+kern-ws-*/

kern_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: kern-sandbox
+Version: 0.1.0
+Summary: Run code in a fast, local, daemonless kernel sandbox — no cloud, no account, no KVM.
+Project-URL: Homepage, https://github.com/getkern/kern
+Project-URL: Source, https://github.com/getkern/kern/tree/main/bindings/python
+Author: getkern
+License: Apache-2.0
+Keywords: agent,ci,code-execution,edge,isolation,namespaces,sandbox,seccomp
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# kern-sandbox
+
+Run LLM/agent-generated code in a fast, **local**, daemonless kernel sandbox from Python.
+
+```python
+import kern_sandbox as kern
+
+# one-shot
+r = kern.run_code("import sys; print(sys.version)")
+print(r.stdout, r.success)
+
+# a session: FILE state persists across steps (a workspace on disk); each step is a fresh box
+with kern.Sandbox(setup="pip install pandas matplotlib") as sbx:
+    sbx.write_file("data.csv", "a,b\n1,2\n3,4\n")
+    r = sbx.run_code("import pandas as pd; print(pd.read_csv('data.csv').shape)")   # (2, 2)
+    sbx.run_code(
+        "import matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as p; "
+        "p.plot([1, 4, 9]); p.savefig('out.png')"
+    )
+    png = sbx.read_file("out.png")   # bytes of the plot the previous step created
+```
+
+A thin, safe wrapper around the [`kern`](https://github.com/getkern/kern) binary — it shells out to
+`kern box`, it does **not** re-implement isolation in Python. Each `run_code`/`run` spawns a fresh,
+ephemeral kernel sandbox (user namespace + seccomp + cgroups). See [Performance](#performance) for
+measured numbers.
+
+## The model: file-state persists, processes are ephemeral
+
+- **File state persists between steps** via a `/workspace` directory on disk, shared into every box.
+  Write a file in one `run_code`, read it in the next.
+- **Processes are ephemeral**: each call is a *fresh* box. **In-memory REPL state does NOT persist** —
+  a `x = 40` set in one call is gone in the next. Write to disk if you need continuity (agents should
+  anyway: it survives crashes and is inspectable).
+
+This is deliberate. It keeps the cold-start/density win (hundreds of ephemeral boxes, not hundreds of
+resident interpreters holding RAM) instead of a cloud-session model. If you need in-memory Jupyter-style
+state, this isn't that — and that's the point.
+
+## Why this and not a cloud sandbox
+
+E2B / Modal / Daytona run code in cloud microVMs — control plane, API key, KVM, network latency.
+**kern-sandbox runs on your own machine, in CI, on an edge box** — no daemon, no cloud, no account,
+no KVM. The sandbox for an agent's dev loop, a CI step, or an air-gapped host.
+
+## Performance
+
+Measured on one x86_64 laptop (kern 0.6.3, `python:3.12-slim`), not aspirational. Your hardware will
+differ — measure and claim your own number.
+
+**Single call, sequential** (p50):
+
+| call (p50) | `enforce_limits=False` | default (`enforce_limits=True`) |
+| --- | --- | --- |
+| `run(["true"])` (bare box) | ~3.5 ms | ~7.5 ms |
+| `run_code("print(1)")` (+ Python interpreter start) | ~16 ms | ~32 ms |
+| `docker run python:3.12-slim python3 -c` | — | ~344 ms |
+
+For reference, `kern box` **natively** (no Python wrapper) is ~1.9 ms — the ~3.5 ms bare-box row is that
+plus the wrapper's subprocess + reader-thread overhead.
+
+`run_code` runs *Python code*, so it pays the **CPython interpreter start** (~12 ms) on top of the box —
+that's a Python cost, not kern's, and it's why `run_code` is ~16 ms, not the bare box's ~3.5 ms. Even so:
+**~16 ms vs Docker's ~344 ms is about 20× faster** for the same task, and we quote the number you get from
+`run_code`, never the bare-box best case dressed up as the code-execution number.
+
+**Concurrency** — the default hard-enforces caps via a per-call systemd scope, which **contends under
+heavy parallelism**. 100 concurrent `run_code` calls, 100/100 succeeded, zero leaked boxes, but:
+
+| 100 concurrent `run_code` | wall | per-call p50 | per-call p95 |
+| --- | --- | --- | --- |
+| default (`enforce_limits=True`) | ~0.58 s | ~510 ms | ~550 ms |
+| `enforce_limits=False` (best-effort caps) | ~0.12 s | ~59 ms | ~89 ms |
+
+If you fire many boxes concurrently and can accept best-effort (not hard-enforced) resource caps, set
+`enforce_limits=False` for the ~5× density win. The default stays hard-enforced and safe.
+
+## Safe by default
+
+A bare `Sandbox()` has **no network, no host mounts, seccomp on, dangerous caps dropped, and a
+mandatory finite timeout**. Every relaxation is an explicit, named argument.
+
+```python
+Sandbox(
+    image="python:3.12-slim",   # OCI image (default: a small Python base)
+    setup="pip install pandas", # the ONLY network window — a separate net-on setup box; run_code is net-off
+    workspace=None,             # None → temp dir, deleted on __exit__; a path → persists across sessions
+    memory_mb=512,
+    cpus=None,                  # CPU cap in cores (e.g. 1.5); None = uncapped
+    pids=256,                   # fork-bomb ceiling
+    timeout_s=30,               # MANDATORY per-call wall-clock limit
+    network=False,              # RELAXES ISOLATION — True shares the host network for every run
+    mounts=None,                # {host_src: box_target} or {src: (target, "ro")}; sensitive sources refused
+    max_output_bytes=64 << 20,  # cap on captured stdout/stderr EACH; overflow discarded, result.truncated set
+    deps_readonly=False,        # True → run_code can't modify setup= deps (blocks cross-run poisoning)
+    enforce_limits=True,        # hard-enforce caps via a systemd scope; False = best-effort, faster under load
+)
+```
+
+Host mounts over sensitive sources (`/`, `/etc`, `$HOME`, the docker socket, …) are **refused even if
+you ask**. Captured output is **bounded** (`max_output_bytes` each) — a flooding box can't OOM the host.
+
+**Network policy:** the network is on **only** during `setup=` (a separate box that dies when setup
+ends); every `run_code` runs network-off. There is no per-call network override — `network=True` is a
+session-level, explicit choice.
+
+**Dependencies (`setup=`)** install into `<workspace>/.deps` (on `PYTHONPATH`). By default that dir is
+writable, so code run in a session *can* modify the deps a later step in the **same session** sees
+(sessions are isolated from each other — distinct workspace). If you run untrusted code and need dep
+integrity across steps, pass `deps_readonly=True`.
+
+## Results, and what a fault means
+
+```python
+@dataclass
+class ExecutionResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+    duration_ms: int
+    fault: SandboxFault | None   # set ONLY when the SANDBOX acted; None for ordinary user-code failures
+    files: list[FileInfo]        # workspace files created/modified this step (.deps excluded)
+    success: bool                # exit_code == 0 AND fault is None
+```
+
+**A Python exception in your code is NOT a fault** — it's `exit_code != 0`, a traceback in `stderr`,
+`fault is None`. `fault` is set only when the sandbox stopped the code:
+
+- `timeout` — the call exceeded `timeout_s` (the binding owns and enforces this deadline).
+- `escape_blocked` — a syscall was blocked by the seccomp filter (SIGSYS).
+- `killed` — the box was SIGKILLed, not by our deadline (message notes it's *likely* OOM; the binding
+  can't read the box cgroup to confirm, so it won't claim `oom` as the type).
+- `startup_failed` — kern couldn't start the box (best-effort, from kern's own diagnostics).
+
+## API
+
+- `kern.run_code(code, **kwargs)` — one-shot: a throwaway `Sandbox` under the hood. Returns an `ExecutionResult`.
+- `Sandbox(...).run_code(code, language="python"|"bash")` — run code on the session workspace (fresh box).
+- `Sandbox(...).run(argv_list)` — run an arbitrary command (an **argv list**, never a shell string).
+- `Sandbox(...).write_file(path, data)` / `.read_file(path)` / `.list_files(subdir="")` — workspace I/O,
+  confined to `/workspace` (symlink- and `..`-safe).
+
+## Threat model (honest)
+
+kern is a **kernel-boundary** sandbox for **your own or semi-trusted** code. The seccomp filter is a
+**denylist** — suitable for semi-trusted agent code, **not** a hard boundary against deliberately
+hostile multi-tenant code. For that, use a microVM (Firecracker / Kata) or gVisor. A deny-by-default
+allowlist mode is on the roadmap. See the project
+[SECURITY.md](https://github.com/getkern/kern/blob/main/SECURITY.md).
+
+## Requirements
+
+The `kern` binary on `PATH` (or set `$KERN_BIN`). Linux only.
+
+## License
+
+Apache-2.0.

kern_sandbox-0.1.0/README.md

@@ -0,0 +1,157 @@
+# kern-sandbox
+
+Run LLM/agent-generated code in a fast, **local**, daemonless kernel sandbox from Python.
+
+```python
+import kern_sandbox as kern
+
+# one-shot
+r = kern.run_code("import sys; print(sys.version)")
+print(r.stdout, r.success)
+
+# a session: FILE state persists across steps (a workspace on disk); each step is a fresh box
+with kern.Sandbox(setup="pip install pandas matplotlib") as sbx:
+    sbx.write_file("data.csv", "a,b\n1,2\n3,4\n")
+    r = sbx.run_code("import pandas as pd; print(pd.read_csv('data.csv').shape)")   # (2, 2)
+    sbx.run_code(
+        "import matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as p; "
+        "p.plot([1, 4, 9]); p.savefig('out.png')"
+    )
+    png = sbx.read_file("out.png")   # bytes of the plot the previous step created
+```
+
+A thin, safe wrapper around the [`kern`](https://github.com/getkern/kern) binary — it shells out to
+`kern box`, it does **not** re-implement isolation in Python. Each `run_code`/`run` spawns a fresh,
+ephemeral kernel sandbox (user namespace + seccomp + cgroups). See [Performance](#performance) for
+measured numbers.
+
+## The model: file-state persists, processes are ephemeral
+
+- **File state persists between steps** via a `/workspace` directory on disk, shared into every box.
+  Write a file in one `run_code`, read it in the next.
+- **Processes are ephemeral**: each call is a *fresh* box. **In-memory REPL state does NOT persist** —
+  a `x = 40` set in one call is gone in the next. Write to disk if you need continuity (agents should
+  anyway: it survives crashes and is inspectable).
+
+This is deliberate. It keeps the cold-start/density win (hundreds of ephemeral boxes, not hundreds of
+resident interpreters holding RAM) instead of a cloud-session model. If you need in-memory Jupyter-style
+state, this isn't that — and that's the point.
+
+## Why this and not a cloud sandbox
+
+E2B / Modal / Daytona run code in cloud microVMs — control plane, API key, KVM, network latency.
+**kern-sandbox runs on your own machine, in CI, on an edge box** — no daemon, no cloud, no account,
+no KVM. The sandbox for an agent's dev loop, a CI step, or an air-gapped host.
+
+## Performance
+
+Measured on one x86_64 laptop (kern 0.6.3, `python:3.12-slim`), not aspirational. Your hardware will
+differ — measure and claim your own number.
+
+**Single call, sequential** (p50):
+
+| call (p50) | `enforce_limits=False` | default (`enforce_limits=True`) |
+| --- | --- | --- |
+| `run(["true"])` (bare box) | ~3.5 ms | ~7.5 ms |
+| `run_code("print(1)")` (+ Python interpreter start) | ~16 ms | ~32 ms |
+| `docker run python:3.12-slim python3 -c` | — | ~344 ms |
+
+For reference, `kern box` **natively** (no Python wrapper) is ~1.9 ms — the ~3.5 ms bare-box row is that
+plus the wrapper's subprocess + reader-thread overhead.
+
+`run_code` runs *Python code*, so it pays the **CPython interpreter start** (~12 ms) on top of the box —
+that's a Python cost, not kern's, and it's why `run_code` is ~16 ms, not the bare box's ~3.5 ms. Even so:
+**~16 ms vs Docker's ~344 ms is about 20× faster** for the same task, and we quote the number you get from
+`run_code`, never the bare-box best case dressed up as the code-execution number.
+
+**Concurrency** — the default hard-enforces caps via a per-call systemd scope, which **contends under
+heavy parallelism**. 100 concurrent `run_code` calls, 100/100 succeeded, zero leaked boxes, but:
+
+| 100 concurrent `run_code` | wall | per-call p50 | per-call p95 |
+| --- | --- | --- | --- |
+| default (`enforce_limits=True`) | ~0.58 s | ~510 ms | ~550 ms |
+| `enforce_limits=False` (best-effort caps) | ~0.12 s | ~59 ms | ~89 ms |
+
+If you fire many boxes concurrently and can accept best-effort (not hard-enforced) resource caps, set
+`enforce_limits=False` for the ~5× density win. The default stays hard-enforced and safe.
+
+## Safe by default
+
+A bare `Sandbox()` has **no network, no host mounts, seccomp on, dangerous caps dropped, and a
+mandatory finite timeout**. Every relaxation is an explicit, named argument.
+
+```python
+Sandbox(
+    image="python:3.12-slim",   # OCI image (default: a small Python base)
+    setup="pip install pandas", # the ONLY network window — a separate net-on setup box; run_code is net-off
+    workspace=None,             # None → temp dir, deleted on __exit__; a path → persists across sessions
+    memory_mb=512,
+    cpus=None,                  # CPU cap in cores (e.g. 1.5); None = uncapped
+    pids=256,                   # fork-bomb ceiling
+    timeout_s=30,               # MANDATORY per-call wall-clock limit
+    network=False,              # RELAXES ISOLATION — True shares the host network for every run
+    mounts=None,                # {host_src: box_target} or {src: (target, "ro")}; sensitive sources refused
+    max_output_bytes=64 << 20,  # cap on captured stdout/stderr EACH; overflow discarded, result.truncated set
+    deps_readonly=False,        # True → run_code can't modify setup= deps (blocks cross-run poisoning)
+    enforce_limits=True,        # hard-enforce caps via a systemd scope; False = best-effort, faster under load
+)
+```
+
+Host mounts over sensitive sources (`/`, `/etc`, `$HOME`, the docker socket, …) are **refused even if
+you ask**. Captured output is **bounded** (`max_output_bytes` each) — a flooding box can't OOM the host.
+
+**Network policy:** the network is on **only** during `setup=` (a separate box that dies when setup
+ends); every `run_code` runs network-off. There is no per-call network override — `network=True` is a
+session-level, explicit choice.
+
+**Dependencies (`setup=`)** install into `<workspace>/.deps` (on `PYTHONPATH`). By default that dir is
+writable, so code run in a session *can* modify the deps a later step in the **same session** sees
+(sessions are isolated from each other — distinct workspace). If you run untrusted code and need dep
+integrity across steps, pass `deps_readonly=True`.
+
+## Results, and what a fault means
+
+```python
+@dataclass
+class ExecutionResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+    duration_ms: int
+    fault: SandboxFault | None   # set ONLY when the SANDBOX acted; None for ordinary user-code failures
+    files: list[FileInfo]        # workspace files created/modified this step (.deps excluded)
+    success: bool                # exit_code == 0 AND fault is None
+```
+
+**A Python exception in your code is NOT a fault** — it's `exit_code != 0`, a traceback in `stderr`,
+`fault is None`. `fault` is set only when the sandbox stopped the code:
+
+- `timeout` — the call exceeded `timeout_s` (the binding owns and enforces this deadline).
+- `escape_blocked` — a syscall was blocked by the seccomp filter (SIGSYS).
+- `killed` — the box was SIGKILLed, not by our deadline (message notes it's *likely* OOM; the binding
+  can't read the box cgroup to confirm, so it won't claim `oom` as the type).
+- `startup_failed` — kern couldn't start the box (best-effort, from kern's own diagnostics).
+
+## API
+
+- `kern.run_code(code, **kwargs)` — one-shot: a throwaway `Sandbox` under the hood. Returns an `ExecutionResult`.
+- `Sandbox(...).run_code(code, language="python"|"bash")` — run code on the session workspace (fresh box).
+- `Sandbox(...).run(argv_list)` — run an arbitrary command (an **argv list**, never a shell string).
+- `Sandbox(...).write_file(path, data)` / `.read_file(path)` / `.list_files(subdir="")` — workspace I/O,
+  confined to `/workspace` (symlink- and `..`-safe).
+
+## Threat model (honest)
+
+kern is a **kernel-boundary** sandbox for **your own or semi-trusted** code. The seccomp filter is a
+**denylist** — suitable for semi-trusted agent code, **not** a hard boundary against deliberately
+hostile multi-tenant code. For that, use a microVM (Firecracker / Kata) or gVisor. A deny-by-default
+allowlist mode is on the roadmap. See the project
+[SECURITY.md](https://github.com/getkern/kern/blob/main/SECURITY.md).
+
+## Requirements
+
+The `kern` binary on `PATH` (or set `$KERN_BIN`). Linux only.
+
+## License
+
+Apache-2.0.

kern_sandbox-0.1.0/kern_sandbox/__init__.py

@@ -0,0 +1,644 @@
+"""kern-sandbox — run LLM/agent-generated code in a fast, local, daemonless kernel sandbox.
+
+    import kern_sandbox as kern
+
+    # one-shot (a throwaway session under the hood)
+    r = kern.run_code("import sys; print(sys.version)")
+    print(r.stdout, r.success)
+
+    # a session: FILE state persists across steps (a workspace on disk), processes are ephemeral
+    with kern.Sandbox(setup="pip install pandas") as sbx:
+        sbx.write_file("data.csv", csv_bytes)
+        r = sbx.run_code("import pandas as pd; print(pd.read_csv('data.csv').shape)")
+        png = sbx.read_file("out.png")
+
+Design — the "middle way" (validated with review):
+  * FILE state persists between steps via a workspace DIRECTORY on the host, bind-mounted into each
+    box. PROCESSES are ephemeral: every run_code()/run() spawns a FRESH box on that shared workspace.
+    There is NO resident interpreter — in-memory REPL state (a `x=40` living in globals) does NOT
+    survive between calls; write to disk if you need continuity. This keeps the cold-start/density
+    win (100s of ephemeral boxes, not 100s of resident pythons) instead of chasing a cloud-session
+    model kern isn't built for.
+  * ONE class (`Sandbox`). `run_code(...)` at module level is literally a throwaway session
+    (`with Sandbox() as s: return s.run_code(...)`), so there is a single, tested security code path —
+    not two Sandbox-like surfaces that drift apart. (# DECISION, reviewer-ratified.)
+  * I/O is HOST-DIRECT: the workspace is a host dir and single-uid maps box-root to the host user, so
+    files the box creates are host-owned — write_file/read_file are plain host filesystem I/O, no
+    `kern cp`, no in-box shim. (`--uid-range` breaks this ownership and is OUT of v1 scope. # DECISION.)
+
+Threat model (honest): kern is a KERNEL-BOUNDARY sandbox for YOUR OWN or SEMI-TRUSTED code. seccomp
+is a DENYLIST — suitable for semi-trusted agent code, NOT a hard boundary against deliberately hostile
+multi-tenant code (for that: a microVM / gVisor). A deny-by-default allowlist mode is on the roadmap.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import signal
+import stat
+import subprocess
+import tempfile
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, Mapping, Sequence
+
+__all__ = [
+    "Sandbox",
+    "ExecutionResult",
+    "SandboxFault",
+    "FileInfo",
+    "SandboxError",
+    "MountRefused",
+    "run_code",
+]
+
+__version__ = "0.1.0"
+
+# DECISION: default image is a small Python base. Criterion "import pandas with no setup" needs a
+# batteries-included image; for v1 we start from a PUBLIC image and let `setup=` bake deps, rather than
+# building+hosting our own (reviewer-ratified FLAG 4). Ship a datascience default when demand justifies.
+_DEFAULT_IMAGE = "python:3.12-slim"
+
+_WORKSPACE = "/workspace"  # where the persistent workspace is mounted inside every box
+_DEPS_DIR = ".deps"  # pip --target dir inside the workspace (added to PYTHONPATH for run_code)
+_ENV_FILE = ".kern-env"  # host-side 0600 env file (kept out of argv so values don't show in `ps`)
+
+# Host paths a `-v` mount must never target — mounting the host's real root/config/secrets into a
+# sandbox defeats the point; the docker socket is the classic escape. A footgun guard: refused even
+# when asked. Absolute, normalized host-SOURCE paths.
+_REFUSED_MOUNT_SOURCES = {
+    "/",
+    "/etc",
+    "/root",
+    "/boot",
+    "/proc",
+    "/sys",
+    "/dev",
+    "/var/run/docker.sock",
+    "/run/docker.sock",
+}
+
+
+class SandboxError(RuntimeError):
+    """A PROGRAMMER/config error, RAISED: bad argument, illegal mount, or `kern` not installed.
+
+    Runtime sandbox events (timeout, blocked escape, OOM-kill) are NOT raised — they are reported as
+    data in ``ExecutionResult.fault`` (a :class:`SandboxFault`). Raising them would force every
+    ``run_code`` into a try/except for what is a normal, expected outcome of running untrusted code.
+    """
+
+
+class MountRefused(SandboxError):
+    """A requested host mount was refused as unsafe (sensitive source, or a relative/escaping path)."""
+
+
+@dataclass
+class SandboxFault:
+    """A SANDBOX-level event that stopped the code — reported as DATA, never raised. ``None`` in a
+    result means the sandbox did nothing: any non-zero exit is the user's code, not a sandbox fault."""
+
+    type: Literal["timeout", "escape_blocked", "killed", "startup_failed"]
+    message: str
+
+
+@dataclass
+class FileInfo:
+    """A file in the workspace and how this step touched it."""
+
+    path: str  # workspace-relative path
+    size: int
+    change: Literal["created", "modified"]
+
+
+@dataclass
+class ExecutionResult:
+    """The outcome of one ``run_code``/``run``. ``fault`` is the source of truth for "did the SANDBOX
+    act"; ``exit_code``/``stdout`` are what the user's code did. ``success`` requires both clean."""
+
+    stdout: str
+    stderr: str
+    exit_code: int
+    duration_ms: int
+    fault: SandboxFault | None = None
+    files: list[FileInfo] = field(default_factory=list)
+    truncated: bool = False  # stdout/stderr hit the capture cap and overflow was discarded
+
+    @property
+    def success(self) -> bool:
+        """True iff the code exited 0 AND no sandbox fault fired."""
+        return self.exit_code == 0 and self.fault is None
+
+    def __bool__(self) -> bool:
+        return self.success
+
+
+class _CappedReader(threading.Thread):
+    """Drain a pipe into a bounded buffer: keep at most ``cap`` bytes but KEEP reading past it
+    (discarding overflow) so a flooding box never blocks on a full pipe. RAM is bounded to ``cap``."""
+
+    def __init__(self, pipe, cap: int) -> None:
+        super().__init__(daemon=True)
+        self._pipe = pipe
+        self._cap = cap
+        self.buf = bytearray()
+        self.truncated = False
+
+    def run(self) -> None:
+        try:
+            while True:
+                chunk = self._pipe.read(65536)
+                if not chunk:
+                    break
+                room = self._cap - len(self.buf)
+                if room > 0:
+                    self.buf += chunk[:room]
+                if len(chunk) > room:
+                    self.truncated = True
+        except (ValueError, OSError):
+            pass
+        finally:
+            try:
+                self._pipe.close()
+            except OSError:
+                pass
+
+
+def _find_kern() -> str:
+    """Locate ``kern``: ``$KERN_BIN`` if set, else the first ``kern`` on ``$PATH``."""
+    env = os.environ.get("KERN_BIN")
+    if env:
+        if not (Path(env).is_file() and os.access(env, os.X_OK)):
+            raise SandboxError(f"$KERN_BIN='{env}' is not an executable file")
+        return env
+    found = shutil.which("kern")
+    if not found:
+        raise SandboxError(
+            "the `kern` binary was not found on PATH — install it "
+            "(https://github.com/getkern/kern) or set $KERN_BIN"
+        )
+    return found
+
+
+def _validate_mount(source: str, target: str) -> tuple[str, str]:
+    """Validate one host->box mount; refuse unsafe sources/targets. Returns (abs_real_source, target)."""
+    if not target.startswith("/"):
+        raise MountRefused(f"mount target must be an absolute path in the box, got {target!r}")
+    if any(c == ".." for c in target.split("/")):
+        raise MountRefused(f"mount target must not contain '..': {target!r}")
+    norm_target = "/" + "/".join(c for c in target.split("/") if c and c != ".")
+    if norm_target in ("/", "/proc", "/sys", "/dev"):
+        raise MountRefused(f"cannot mount over the box essential mount {norm_target!r}")
+    src = Path(source)
+    if not src.is_absolute():
+        raise MountRefused(f"mount source must be an absolute host path, got {source!r}")
+    real = os.path.realpath(source)  # resolve symlinks BEFORE the sensitive-set check
+    if real in _REFUSED_MOUNT_SOURCES or real == os.path.realpath(os.path.expanduser("~")):
+        raise MountRefused(
+            f"refusing to mount the sensitive host path {real!r} into a sandbox "
+            "(this would defeat the isolation)"
+        )
+    if not Path(real).exists():
+        raise MountRefused(f"mount source does not exist: {source!r}")
+    return real, target
+
+
+# Signal-derived exit codes (128 + signum) we classify.
+_EXIT_SIGKILL = 137  # 128 + 9  — SIGKILL: timeout backstop or OOM (indistinguishable without cgroup)
+_EXIT_SIGSYS = 159  # 128 + 31 — SIGSYS: a seccomp-denied syscall = a blocked escape attempt
+_EXIT_SIGTERM = 143  # 128 + 15 — SIGTERM: kern's --timeout backstop reaping the box (SIGTERM→SIGKILL)
+
+
+@dataclass
+class Sandbox:
+    """A configured kernel sandbox. FILE state persists across ``run_code``/``run`` in a workspace on
+    disk; each call runs in a FRESH ephemeral box. Safe by default; every relaxing arg says so.
+
+    Args:
+        image: OCI image the box runs from. Default: a small Python image.
+        setup: a shell command run ONCE at ``__enter__`` in a NETWORK-ENABLED setup box (e.g.
+            ``"pip install pandas"``). This is the ONLY moment the network is on; every ``run_code`` is
+            network-off. Deps installed to ``<workspace>/.deps`` and put on ``PYTHONPATH``.
+        workspace: host directory to use as the persistent workspace. ``None`` (default) → a temp dir
+            created on ``__enter__`` and DELETED on ``__exit__`` (session-ephemeral). A given path is
+            validated like a mount, is NOT deleted on exit, and its contents persist across sessions.
+        memory_mb: RAM cap (kern ``--memory``). Default 512.
+        cpus: CPU cap in cores; ``None`` = uncapped (kern ``--cpus``).
+        pids: task/fork-bomb ceiling (kern ``--pids-limit``). Default 256.
+        timeout_s: MANDATORY per-call wall-clock limit. The BINDING owns this deadline (it kills the
+            box), so a ``timeout`` fault is a known fact, never guessed. Default 30.
+        network: **RELAXES ISOLATION.** ``True`` shares the host network for every ``run_code`` (kern
+            ``--net``). Default ``False``. There is no per-call network override — network is a
+            session-level, explicit choice.
+        mounts: extra host paths to bind, ``{host_src: box_target}`` (or ``{src: (target, "ro")}``).
+            Sensitive sources are refused. The workspace is mounted automatically; this is for extras.
+        env: extra environment variables for the workload.
+        max_output_bytes: cap on captured stdout/stderr EACH; a flooding box can't OOM the host.
+        enforce_limits: ``True`` (default) hard-enforces caps via a systemd scope (~6 ms start);
+            ``False`` skips it for a ~3 ms start (best-effort caps).
+    """
+
+    image: str = _DEFAULT_IMAGE
+    setup: str | None = None
+    workspace: str | None = None
+    memory_mb: int | None = 512
+    cpus: float | None = None
+    pids: int | None = 256
+    timeout_s: int = 30
+    network: bool = False
+    mounts: Mapping[str, "str | tuple[str, str]"] | None = None
+    env: Mapping[str, str] | None = None
+    max_output_bytes: int = 64 * 1024 * 1024
+    enforce_limits: bool = True
+    deps_readonly: bool = False  # mount setup= deps read-only for run_code (block cross-run poisoning)
+
+    _kern: str = field(default="", repr=False)
+    _mount_args: list = field(default_factory=list, init=False, repr=False)
+    _ws: str = field(default="", init=False, repr=False)
+    _own_ws: bool = field(default=False, init=False, repr=False)  # we created it → we delete it
+    _entered: bool = field(default=False, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        if self.timeout_s is None or self.timeout_s <= 0:
+            raise SandboxError("timeout_s must be a positive number of seconds")
+        if self.max_output_bytes <= 0:
+            raise SandboxError("max_output_bytes must be positive")
+        self._mount_args = []
+        if self.mounts:
+            for source, spec in self.mounts.items():
+                if isinstance(spec, tuple):
+                    target, mode = spec
+                    if mode not in ("ro", "rw"):
+                        raise MountRefused(f"mount mode must be 'ro' or 'rw', got {mode!r}")
+                    ro = mode == "ro"
+                else:
+                    target, ro = spec, False
+                real, tgt = _validate_mount(source, target)
+                self._mount_args += ["-v", f"{real}:{tgt}:ro" if ro else f"{real}:{tgt}"]
+        self._kern = _find_kern()
+
+    # -- lifecycle -----------------------------------------------------------------------------------
+
+    def __enter__(self) -> "Sandbox":
+        if self.workspace is None:
+            self._ws = os.path.realpath(tempfile.mkdtemp(prefix="kern-ws-"))
+            self._own_ws = True
+        else:
+            # A caller-supplied workspace is host input → validate it like a mount source, and DON'T
+            # delete it on exit (its contents persist across sessions — documented).
+            _validate_mount(self.workspace, _WORKSPACE)
+            self._ws = os.path.realpath(self.workspace)
+            Path(self._ws).mkdir(parents=True, exist_ok=True)
+            self._own_ws = False
+        self._entered = True
+        if self.setup:
+            self._run_setup(self.setup)
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        if self._own_ws and self._ws:
+            shutil.rmtree(self._ws, ignore_errors=True)
+        self._entered = False
+
+    def _require_entered(self) -> None:
+        if not self._entered:
+            raise SandboxError("use the Sandbox as a context manager: `with Sandbox() as s: ...`")
+
+    # -- the box invocation --------------------------------------------------------------------------
+
+    def _base_argv(self, name: str, *, network: bool, timeout_s: int, is_setup: bool = False) -> list[str]:
+        argv = [self._kern, "box", name, "--image", self.image, "--ro", "-v", f"{self._ws}:{_WORKSPACE}",
+                "--workdir", _WORKSPACE]
+        # deps_readonly: mount <workspace>/.deps read-only OVER the writable workspace for run_code boxes
+        # (not the setup box, which must populate it). Closes the cross-run dep-poisoning window within a
+        # session for tighter (still semi-trusted) workloads. Default off — deps writable, documented.
+        if self.deps_readonly and not is_setup:
+            deps = os.path.join(self._ws, _DEPS_DIR)
+            if os.path.isdir(deps):
+                argv += ["-v", f"{deps}:{_WORKSPACE}/{_DEPS_DIR}:ro"]
+        # kern's own --timeout is a tight BACKSTOP just beyond our deadline: it is the RELIABLE killer of
+        # the in-PID-namespace box (a CPU-bound box survives a SIGKILL of kern's parent process, but not
+        # kern's own timeout teardown). OUR proc.wait deadline is the authority that LABELS a `timeout`
+        # fault; kern's backstop guarantees the box is actually gone a few seconds later.
+        argv += ["--timeout", str(timeout_s + 5)]
+        if self.memory_mb is not None:
+            argv += ["--memory", f"{self.memory_mb}m"]
+        if self.cpus is not None:
+            argv += ["--cpus", str(self.cpus)]
+        if self.pids is not None:
+            argv += ["--pids-limit", str(self.pids)]
+        if network:
+            argv += ["--net"]
+        argv += self._mount_args
+        merged_env = dict(self.env or {})
+        # Deps installed by `setup` live in <workspace>/.deps — put them on PYTHONPATH for run_code.
+        merged_env.setdefault("PYTHONPATH", f"{_WORKSPACE}/{_DEPS_DIR}")
+        # Pass the workload env via a private --env-file, NOT `--env K=V` on argv: an argv value is
+        # visible in `ps` / /proc/<pid>/cmdline to any local user for the box's lifetime, and this
+        # component's whole point is running untrusted code beside sensitive data (a credential in
+        # `env=` would leak). The file lives in our own 0700 mkdtemp workspace, written 0600, so it is
+        # not readable by other users; kern reads it before the box's env is set up. (Hacker-mode audit.)
+        if merged_env:
+            env_path = os.path.join(self._ws, _ENV_FILE)
+            fd = os.open(env_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+            try:
+                # K=V lines; values are single-line by construction (a NUL is rejected in _spawn, and a
+                # newline in a value would split the record — reject it here so it can't smuggle a var).
+                lines = []
+                for k, v in merged_env.items():
+                    if "\n" in k or "\n" in v or "\0" in k or "\0" in v:
+                        raise SandboxError(f"env var {k!r} must not contain a newline or NUL")
+                    lines.append(f"{k}={v}\n")
+                os.write(fd, "".join(lines).encode())
+            finally:
+                os.close(fd)
+            argv += ["--env-file", env_path]
+        return argv
+
+    def _spawn(self, command: Sequence[str], *, network: bool, timeout_s: int, is_setup: bool = False) -> ExecutionResult:
+        for part in command:
+            if "\0" in part:
+                raise SandboxError("command/code must not contain a NUL byte")
+        before = self._snapshot()
+        name = _unique_name()
+        argv = self._base_argv(name, network=network, timeout_s=timeout_s, is_setup=is_setup) + ["--"] + list(command)
+        child_env = {**os.environ, "KERN_ACCEPT_EULA": "1"}
+        if not self.enforce_limits:
+            child_env["KERN_NO_SCOPE"] = "1"
+        started = time.monotonic()
+        try:
+            # start_new_session so the box + kern share a process group we can signal as a unit.
+            proc = subprocess.Popen(  # noqa: S603 — argv list, no shell
+                argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE, env=child_env,
+                start_new_session=True,
+            )
+        except FileNotFoundError as e:
+            raise SandboxError(f"could not execute kern: {e}") from e
+        except OSError as e:
+            # E2BIG (argv too long) and other spawn-time OS errors → a clean typed error, not a raw
+            # OSError leaking out of the binding. (run_code already routes large code via a file.)
+            raise SandboxError(f"could not spawn the box: {e}") from e
+        out = _CappedReader(proc.stdout, self.max_output_bytes)
+        err = _CappedReader(proc.stderr, self.max_output_bytes)
+        out.start()
+        err.start()
+        we_timed_out = False
+        try:
+            proc.wait(timeout=timeout_s)  # OUR deadline — the authority for a `timeout` fault
+        except subprocess.TimeoutExpired:
+            we_timed_out = True
+            self._teardown(proc, name, child_env)
+        # Join readers, but BOUNDED: a CPU-bound box can survive our signals and hold the pipe open
+        # until kern's own --timeout backstop reaps it a few seconds later; never hang the caller on it.
+        join_deadline = 8.0 if we_timed_out else None
+        out.join(join_deadline)
+        err.join(join_deadline)
+        # Reap the process so returncode is populated and no zombie lingers (bounded — the backstop has
+        # reaped the box by now in the timeout case).
+        try:
+            proc.wait(timeout=8.0)
+        except subprocess.TimeoutExpired:
+            pass
+        wall_ms = int((time.monotonic() - started) * 1000)
+        stdout = out.buf.decode("utf-8", "replace")
+        stderr = err.buf.decode("utf-8", "replace")
+        rc = proc.returncode if proc.returncode is not None else -1
+        fault = self._classify(rc, stderr, we_timed_out)
+        files = self._diff(before)
+        return ExecutionResult(
+            stdout=stdout,
+            stderr=stderr,
+            exit_code=rc,
+            duration_ms=wall_ms,
+            fault=fault,
+            files=files,
+            truncated=out.truncated or err.truncated,
+        )
+
+    def _teardown(self, proc: "subprocess.Popen", name: str, child_env: dict) -> None:
+        """Best-effort tear down a timed-out box. Defense in depth, because a CPU-bound box in its own
+        PID namespace survives a plain SIGKILL of kern's parent process: (1) `kern stop` — the intended
+        teardown (cgroup-kill); (2) SIGKILL the whole process group; (3) SIGKILL the parent. kern's own
+        --timeout backstop guarantees the box is gone shortly regardless. We never block here."""
+
+        try:
+            subprocess.run(
+                [self._kern, "stop", name], env=child_env, capture_output=True, timeout=5
+            )
+        except (OSError, subprocess.SubprocessError):
+            pass
+        try:
+            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+        except (OSError, ProcessLookupError):
+            pass
+        try:
+            proc.kill()
+        except OSError:
+            pass
+
+    def _classify(self, rc: int, stderr: str, we_timed_out: bool) -> SandboxFault | None:
+        # ORDER IS A SECURITY PROPERTY. The classes that are DETERMINISTIC by exit code are decided
+        # FIRST, BEFORE we ever look at stderr — because stderr is a channel the workload controls, and
+        # `startup_failed` is recognised by a pattern on it. If we checked the stderr marker first, a
+        # workload could print "error: sandbox:" and exit with SIGSYS and we'd mislabel a blocked escape
+        # as a mere startup failure — hiding a security event behind a benign one. So: our-deadline →
+        # SIGSYS → SIGKILL, all by exit code, THEN the stderr-marker heuristic as the LAST resort.
+        # (Same discipline as the tar vetter: never make a security decision by parsing an
+        # adversary-influenceable channel.)
+        if we_timed_out:
+            # OUR deadline fired and we killed the box — a known fact, never guessed.
+            return SandboxFault("timeout", f"exceeded the {self.timeout_s}s time limit (killed by the binding)")
+        if rc == _EXIT_SIGSYS:
+            # A seccomp-denied syscall. Decided by exit code, so no stderr content can mask it.
+            return SandboxFault("escape_blocked", "a syscall was blocked by the seccomp filter (SIGSYS)")
+        if rc == _EXIT_SIGKILL:
+            # SIGKILL not from our deadline: almost always the cgroup OOM-killer, but the binding can't
+            # read the box's memory.events (kern doesn't expose the cgroup path — verified), so we do
+            # NOT claim "oom" as the type. Honest: type=killed, message carries the likely cause.
+            return SandboxFault("killed", "the box was killed (SIGKILL) — likely out of memory (exit 137)")
+        if rc in (_EXIT_SIGTERM, -signal.SIGTERM):
+            # SIGTERM without our deadline firing = kern's OWN --timeout backstop reaped the box (it
+            # SIGTERMs, then SIGKILLs after a grace). The box exceeded its time limit; label it timeout,
+            # noting the backstop caught it rather than our own wait.
+            return SandboxFault("timeout", "the box exceeded its time limit (reaped by kern's timeout backstop)")
+        if rc == -signal.SIGKILL:
+            # Negative == killed by signal N (subprocess convention) — SIGKILL surfaced as -9.
+            return SandboxFault("killed", "the box was killed (SIGKILL) — likely out of memory")
+        # LAST resort, heuristic: a non-zero exit that is none of the deterministic classes above, whose
+        # stderr carries kern's OWN setup-diagnostic markers (printed by the parent before the box runs).
+        # Heuristic because stderr is workload-influenceable — but it can only ever mislabel an ordinary
+        # non-zero user exit as startup_failed, never mask an escape/timeout/kill (those were decided
+        # above by exit code). Documented as best-effort.
+        if rc != 0 and _looks_like_startup_failure(stderr):
+            return SandboxFault("startup_failed", stderr.strip()[:500])
+        # exit 139 (SIGSEGV) and any other non-zero exit are the USER's code failing — a normal Result.
+        return None
+
+    # -- workspace file I/O (host-direct; single-uid → box files are host-owned) ---------------------
+
+    def _ws_path(self, rel: str) -> str:
+        """Resolve a workspace-relative path for host-side I/O, refusing any escape out of the workspace.
+
+        Containment is checked on the requested path LEXICALLY (normalize `..`/`.`), NOT by resolving
+        symlinks in it — a symlink the box created can point at a box-absolute target like
+        `/workspace/x` that doesn't exist on the host, and `realpath`-ing it would both false-positive
+        (a legitimate INTERNAL symlink) and, worse, could be steered to follow a link out of the tree.
+        So: lexically contain the requested name here, then open the final component with O_NOFOLLOW
+        (in read/write) so a symlinked LAST component can't redirect the host I/O outside the workspace.
+        """
+        base = self._ws  # canonical since enter — no per-walk re-resolution
+        # Lexical containment: join + normpath collapses `..`, then require it stays under base.
+        full = os.path.normpath(os.path.join(base, rel))
+        if full != base and not full.startswith(base + os.sep):
+            raise SandboxError(f"path escapes the workspace: {rel!r}")
+        return full
+
+    def write_file(self, path: str, data: bytes | str) -> None:
+        """Write ``data`` to ``path`` (workspace-relative) — host-direct, so the box sees it next run.
+        The final component is opened O_NOFOLLOW: a symlink the box planted there can't redirect the
+        write outside the workspace (it fails instead)."""
+        self._require_entered()
+        full = self._ws_path(path)
+        Path(full).parent.mkdir(parents=True, exist_ok=True)
+        payload = data.encode() if isinstance(data, str) else data
+        flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0)
+        try:
+            fd = os.open(full, flags, 0o644)
+        except OSError as e:
+            raise SandboxError(f"cannot write {path!r}: {e}") from e
+        with os.fdopen(fd, "wb") as f:
+            f.write(payload)
+
+    def read_file(self, path: str) -> bytes:
+        """Read ``path`` (workspace-relative) from the workspace — host-direct. The final component is
+        opened O_NOFOLLOW: a symlink there can't redirect the read outside the workspace."""
+        self._require_entered()
+        full = self._ws_path(path)
+        flags = os.O_RDONLY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0)
+        try:
+            fd = os.open(full, flags)
+        except OSError as e:
+            raise SandboxError(f"cannot read {path!r}: {e}") from e
+        with os.fdopen(fd, "rb") as f:
+            return f.read()
+
+    def list_files(self, subdir: str = "") -> list[FileInfo]:
+        """List files under the workspace (excluding the ``.deps`` install dir)."""
+        self._require_entered()
+        root = self._ws_path(subdir) if subdir else self._ws  # _ws is canonical (set at enter)
+        return [FileInfo(path=p, size=s, change="created") for p, (_, s) in self._walk(root).items()]
+
+    # -- setup (the only network window) -------------------------------------------------------------
+
+    def _run_setup(self, cmd: str) -> None:
+        # DECISION (reviewer-ratified C): the network is ON only here, in a SEPARATE setup box that
+        # dies at the end. It installs into <workspace>/.deps; every run_code box is network-off.
+        install = f"pip install --target {_WORKSPACE}/{_DEPS_DIR} --no-cache-dir --disable-pip-version-check"
+        # If the caller gave a bare `pip install X`, route it to the deps dir; else run as-is (net-on).
+        shell_cmd = cmd
+        if cmd.strip().startswith("pip install "):
+            shell_cmd = install + " " + cmd.strip()[len("pip install ") :]
+        r = self._spawn(["sh", "-c", shell_cmd], network=True, timeout_s=max(self.timeout_s, 120), is_setup=True)
+        if not r.success:
+            raise SandboxError(f"setup failed (exit {r.exit_code}): {(r.stderr or r.stdout).strip()[:400]}")
+
+    # -- files diff (created/modified; excludes .deps) -----------------------------------------------
+
+    def _snapshot(self) -> dict[str, tuple[int, int]]:
+        return self._walk(self._ws)  # _ws is canonical (set at enter)
+
+    def _walk(self, root: str) -> dict[str, tuple[int, int]]:
+        """Map WORKSPACE-relative path -> (mtime_ns, size), skipping .deps, our env-file, and symlinks.
+        `root` is where to walk (the workspace, or a subdir for `list_files(subdir)`); paths are ALWAYS
+        made relative to the workspace root so `list_files("sub")` returns `sub/a.txt`, composable with
+        `read_file` (that was a regression when `root` doubled as the base). One lstat per file: S_ISREG
+        excludes non-regular files AND symlinks in a single syscall (a symlink's lstat mode is never
+        S_ISREG) — no extra isfile()/islink() stats."""
+        base = os.path.realpath(self._ws)
+        out: dict[str, tuple[int, int]] = {}
+        for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+            dirnames[:] = [d for d in dirnames if d != _DEPS_DIR]  # exclude deps from the diff
+            for fn in filenames:
+                fp = os.path.join(dirpath, fn)
+                try:
+                    st = os.lstat(fp)
+                except OSError:
+                    continue
+                if not stat.S_ISREG(st.st_mode):
+                    continue
+                rel = os.path.relpath(fp, base)
+                if rel == _ENV_FILE:
+                    continue  # our private host-side --env-file, not a user artifact
+                out[rel] = (st.st_mtime_ns, st.st_size)
+        return out
+
+    def _diff(self, before: dict[str, tuple[int, int]]) -> list[FileInfo]:
+        after = self._snapshot()
+        files: list[FileInfo] = []
+        for rel, (mtime, size) in after.items():
+            if rel not in before:
+                files.append(FileInfo(path=rel, size=size, change="created"))
+            elif before[rel] != (mtime, size):
+                files.append(FileInfo(path=rel, size=size, change="modified"))
+        return files
+
+    # -- the two ways to run code --------------------------------------------------------------------
+
+    # Above this size, pass code via a file in the workspace instead of `-c <code>` on the argv, so a
+    # large agent-generated script can't blow ARG_MAX (~2 MB) with a raw OSError. Well under the limit.
+    _INLINE_CODE_MAX = 128 * 1024
+
+    def run_code(self, code: str, *, language: Literal["python", "bash"] = "python") -> ExecutionResult:
+        """Run a snippet of ``code`` on the workspace in a fresh, network-off box. File state written to
+        the workspace persists to the next call; in-memory state does NOT (fresh process each time).
+        Large code is written to a workspace file and executed from there (transparent to the caller),
+        so an arbitrarily large script works instead of hitting the argv length limit."""
+        self._require_entered()
+        if language not in ("python", "bash"):
+            raise SandboxError(f"unsupported language {language!r} (v1: 'python' | 'bash')")
+        runner = "python3" if language == "python" else "sh"
+        if len(code.encode()) > self._INLINE_CODE_MAX:
+            # Write to a per-call cell file in the workspace and run it by path (no argv-size limit).
+            cell = f".cell-{uuid.uuid4().hex[:8]}.{'py' if language == 'python' else 'sh'}"
+            self.write_file(cell, code)
+            command: list[str] = [runner, f"{_WORKSPACE}/{cell}"]
+        else:
+            command = [runner, "-c", code]
+        return self._spawn(command, network=self.network, timeout_s=self.timeout_s)
+
+    def run(self, command: Sequence[str]) -> ExecutionResult:
+        """Run an arbitrary ``command`` (an argv LIST, never a shell string) in a fresh box."""
+        self._require_entered()
+        if isinstance(command, str):
+            raise SandboxError('run() takes an argv LIST, not a string. Use run(["sh","-c","..."]).')
+        if not command:
+            raise SandboxError("run() needs a non-empty command")
+        return self._spawn(command, network=self.network, timeout_s=self.timeout_s)
+
+
+def _unique_name() -> str:
+    return "pysbx-" + uuid.uuid4().hex[:12]
+
+
+def _looks_like_startup_failure(stderr: str) -> bool:
+    """True iff kern (the PARENT, before the box exists) failed to start the box. Anchored on kern's own
+    diagnostic prefixes — printed by kern, not by the workload — so the workload can't forge them by
+    writing the marker to its own stderr. (Same discipline as the tar vetter: don't trust text the
+    adversary controls; kern's setup errors precede any workload output and carry kern's prefixes.)"""
+    markers = ("kern:", "error: pull:", "error: sandbox:", "error: box:", "error: oci:", "error: image:")
+    for line in stderr.splitlines():
+        s = line.lstrip()
+        if "sandbox setup failed" in s or any(s.startswith(m) for m in markers):
+            return True
+    return False
+
+
+def run_code(code: str, *, language: Literal["python", "bash"] = "python", **kwargs: object) -> ExecutionResult:
+    """One-shot convenience: run ``code`` in a throwaway session (workspace created and deleted). This is
+    literally ``with Sandbox(**kwargs) as s: return s.run_code(code)`` — one tested code path, no state
+    persists. For multi-step work (write a file, then read it), use ``Sandbox`` as a context manager."""
+    with Sandbox(**kwargs) as s:  # type: ignore[arg-type]
+        return s.run_code(code, language=language)

kern_sandbox-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kern-sandbox"
+version = "0.1.0"
+description = "Run code in a fast, local, daemonless kernel sandbox — no cloud, no account, no KVM."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "getkern" }]
+keywords = ["sandbox", "isolation", "namespaces", "seccomp", "agent", "code-execution", "edge", "ci"]
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.urls]
+Homepage = "https://github.com/getkern/kern"
+Source = "https://github.com/getkern/kern/tree/main/bindings/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["kern_sandbox"]

kern_sandbox-0.1.0/tests/test_sandbox.py

@@ -0,0 +1,297 @@
+"""Tests for kern_sandbox (v1 — the middle-way session model).
+
+  * UNIT tests (always run): fail-closed defaults, mount/workspace guards, taxonomy plumbing. No kern.
+  * INTEGRATION tests (skipped unless a runnable `kern` is present): the brief's acceptance criteria
+    against real ephemeral boxes on a persistent workspace.
+
+Run: `pytest`  (integration auto-skips without a real kern; set `KERN_BIN=/path/to/kern`).
+"""
+
+import os
+import shutil
+import time
+
+import pytest
+
+import kern_sandbox as kern
+from kern_sandbox import ExecutionResult, MountRefused, Sandbox, SandboxError
+
+_FAKE_KERN = shutil.which("true") or "/bin/true"
+
+
+def _cfg(**kw):
+    """Construct a Sandbox with a fake kern, restoring the real $KERN_BIN so integration tests still
+    see the real binary (the leak that once made every box shell out to /bin/true)."""
+    prev = os.environ.get("KERN_BIN")
+    os.environ["KERN_BIN"] = _FAKE_KERN
+    try:
+        return Sandbox(**kw)
+    finally:
+        if prev is None:
+            os.environ.pop("KERN_BIN", None)
+        else:
+            os.environ["KERN_BIN"] = prev
+
+
+# ---------------------------------------------------------------------------
+# UNIT
+# ---------------------------------------------------------------------------
+
+
+def test_defaults_are_fail_closed():
+    s = _cfg()
+    assert s.network is False and s.timeout_s > 0
+    assert s.memory_mb is not None and s.pids is not None
+    argv = s._base_argv("n", network=False, timeout_s=s.timeout_s)
+    assert "--net" not in argv and "--timeout" in argv and "--ro" in argv
+
+
+def test_timeout_is_mandatory():
+    for bad in (None, 0, -5):
+        with pytest.raises(SandboxError):
+            _cfg(timeout_s=bad)
+
+
+def test_network_is_opt_in_and_session_level():
+    assert "--net" not in _cfg()._base_argv("n", network=False, timeout_s=30)
+    assert "--net" in _cfg(network=True)._base_argv("n", network=True, timeout_s=30)
+
+
+@pytest.mark.parametrize(
+    "mounts",
+    [
+        {"/": "/host"},
+        {"/etc": "/etc-host"},
+        {"/var/run/docker.sock": "/sock"},
+        {"/tmp": "/"},
+        {"/tmp": "/proc"},
+        {"/tmp": "/foo/../bar"},
+        {"relative/x": "/x"},
+        {"/definitely-not-here-xyz": "/x"},
+    ],
+)
+def test_dangerous_mounts_refused(mounts):
+    with pytest.raises(MountRefused):
+        _cfg(mounts=mounts)
+
+
+def test_home_mount_refused():
+    with pytest.raises(MountRefused):
+        _cfg(mounts={os.path.expanduser("~"): "/home-x"})
+
+
+def test_run_requires_context_manager():
+    with pytest.raises(SandboxError):
+        _cfg().run_code("print(1)")  # not entered
+
+
+def test_run_rejects_shell_string():
+    s = _cfg()
+    s._entered = True  # bypass ctx for the pure-guard check
+    with pytest.raises(SandboxError):
+        s.run("echo hi")
+
+
+def test_result_success_semantics():
+    from kern_sandbox import SandboxFault
+
+    assert ExecutionResult("", "", 0, 1).success is True
+    assert ExecutionResult("", "", 1, 1).success is False
+    assert ExecutionResult("", "", 0, 1, fault=SandboxFault("timeout", "x")).success is False
+
+
+def test_classify_order_escape_not_masked_by_stderr_marker():
+    # SECURITY REGRESSION: a workload can print kern's setup marker ("error: sandbox:") to its own
+    # stderr and exit with SIGSYS. The classifier MUST still call it escape_blocked (decided by exit
+    # code), NOT startup_failed (the stderr-marker heuristic) — else a blocked escape hides behind a
+    # benign "startup failed" label. Deterministic classes are checked before the stderr marker.
+    s = _cfg()
+    forged = "error: sandbox: totally not a real kern setup error\n"
+    assert s._classify(159, forged, False).type == "escape_blocked"  # SIGSYS wins over the marker
+    assert s._classify(137, forged, False).type == "killed"  # SIGKILL wins over the marker
+    assert s._classify(1, forged, False).type == "startup_failed"  # plain non-zero: marker heuristic
+    assert s._classify(1, "boom\n", False) is None  # non-zero, no marker: user code, no fault
+
+
+def test_classify_signal_exit_codes():
+    # Every signal-derived exit maps to the right fault (or None for user crashes).
+    s = _cfg()
+    assert s._classify(143, "", False).type == "timeout"  # SIGTERM = kern backstop reap
+    assert s._classify(-15, "", False).type == "timeout"
+    assert s._classify(137, "", False).type == "killed"  # SIGKILL = likely OOM
+    assert s._classify(-9, "", False).type == "killed"
+    assert s._classify(159, "", False).type == "escape_blocked"  # SIGSYS
+    assert s._classify(139, "", False) is None  # SIGSEGV = user code crash, not a fault
+    assert s._classify(1, "", False) is None  # ordinary non-zero user exit
+
+
+# ---------------------------------------------------------------------------
+# INTEGRATION — the brief's acceptance criteria
+# ---------------------------------------------------------------------------
+
+
+def _kern_runnable() -> bool:
+    k = os.environ.get("KERN_BIN") or shutil.which("kern")
+    return bool(k) and k != _FAKE_KERN and os.access(k, os.X_OK)
+
+
+integration = pytest.mark.skipif(not _kern_runnable(), reason="no runnable kern (set KERN_BIN)")
+
+
+@pytest.fixture(autouse=True)
+def _eula():
+    os.environ.setdefault("KERN_ACCEPT_EULA", "1")
+
+
+@integration
+def test_c2_file_state_persists_between_steps():
+    with Sandbox(timeout_s=30) as s:
+        s.run_code("open('/workspace/x.txt','w').write('40')")
+        r = s.run_code("print(int(open('/workspace/x.txt').read()) + 2)")
+    assert r.stdout.strip() == "42" and r.success
+
+
+@integration
+def test_c3_write_file_then_read_csv():
+    with Sandbox(setup="pip install pandas", timeout_s=60) as s:
+        s.write_file("data.csv", "a,b\n1,2\n3,4\n")
+        r = s.run_code("import pandas as pd; print(pd.read_csv('/workspace/data.csv').shape)")
+    assert "(2, 2)" in r.stdout and r.success and r.fault is None
+
+
+@integration
+def test_c4_infinite_loop_times_out():
+    with Sandbox(timeout_s=4) as s:
+        t = time.monotonic()
+        r = s.run_code("while True: pass")
+        dt = time.monotonic() - t
+    assert r.fault is not None and r.fault.type == "timeout"
+    assert not r.success and dt < 16  # our deadline labels it; not the 21s backstop-only path
+
+
+@integration
+def test_c5a_write_outside_workspace_blocked_not_crash():
+    with Sandbox(timeout_s=20) as s:
+        r = s.run_code("open('/evil','w').write('x')")
+    # blocked in fact (read-only root), surfaced as the user's non-zero exit — NOT a sandbox crash,
+    # NOT a silent success. (Filesystem denial is indistinguishable from a normal PermissionError, so
+    # it is not labelled escape_blocked — that label is reserved for SIGSYS; see c5b.)
+    assert not r.success and "Read-only" in r.stderr
+
+
+@integration
+def test_c5b_blocked_syscall_is_escape_blocked():
+    with Sandbox(timeout_s=20) as s:
+        r = s.run_code("import ctypes; ctypes.CDLL(None).mount(0, 0, 0, 0, 0)")
+    assert r.fault is not None and r.fault.type == "escape_blocked"
+
+
+@integration
+def test_result_files_created_then_modified():
+    with Sandbox(timeout_s=20) as s:
+        r1 = s.run_code("open('/workspace/f.txt','w').write('aaa')")
+        r2 = s.run_code("open('/workspace/f.txt','w').write('bbbb')")
+    assert any(f.change == "created" for f in r1.files)
+    assert any(f.change == "modified" for f in r2.files)
+
+
+@integration
+def test_deps_excluded_from_files_diff():
+    # A pip-installed tree lives in .deps and must NOT flood result.files.
+    with Sandbox(setup="pip install beautifulsoup4", timeout_s=90) as s:
+        r = s.run_code("import bs4; print(bs4.__name__)")
+    assert r.success and all(".deps" not in f.path for f in r.files)
+
+
+@integration
+def test_deps_readonly_blocks_cross_run_poisoning():
+    # With deps_readonly, run_code cannot write into the setup= deps dir (RO submount).
+    with Sandbox(setup="pip install beautifulsoup4", deps_readonly=True, timeout_s=90) as s:
+        r = s.run_code("open('/workspace/.deps/poison.py', 'w').write('x')")
+    assert not r.success  # write into .deps refused (read-only)
+
+
+@integration
+def test_read_write_are_symlink_and_traversal_safe():
+    # SECURITY: host-direct I/O must not follow a symlink the box planted (O_NOFOLLOW) nor a `..`
+    # traversal (lexical containment), while normal files and nested subdirs still work.
+    with Sandbox(timeout_s=20) as s:
+        s.write_file("real.txt", "dati")
+        assert s.read_file("real.txt") == b"dati"
+        s.write_file("a/b/c.txt", "nested")
+        assert s.read_file("a/b/c.txt") == b"nested"
+        s.run_code('import os; os.symlink("/etc/passwd", "/workspace/bad")')
+        with pytest.raises(SandboxError):
+            s.read_file("bad")  # O_NOFOLLOW blocks a symlinked final component
+        with pytest.raises(SandboxError):
+            s.read_file("../../../etc/passwd")  # lexical `..` containment
+
+
+@integration
+def test_box_cannot_read_host_file_by_absolute_path(tmp_path):
+    secret = tmp_path / "host-secret.txt"
+    secret.write_text("TOP-SECRET-HOST")
+    with Sandbox(timeout_s=20) as s:
+        r = s.run_code(f"print(open({str(secret)!r}).read())")
+    assert not r.success and "TOP-SECRET" not in r.stdout
+
+
+@integration
+def test_fork_bomb_contained_by_pids_limit():
+    with Sandbox(pids=32, timeout_s=20) as s:
+        r = s.run_code(
+            "import os\nn=0\nwhile n<10000:\n"
+            "  try:\n    pid=os.fork()\n    (os._exit(0) if pid==0 else None); n+=1\n"
+            "  except OSError:\n    print('blocked', n); break"
+        )
+    assert "blocked" in r.stdout  # pids.max stopped the fork bomb before the timeout
+
+
+@integration
+def test_large_code_runs_via_file_not_argv():
+    # A big generated script must not hit ARG_MAX — run_code routes >128 KiB via a workspace file.
+    code = "# " + "padding " * 20000 + "\nprint('big-ok')"  # ~156 KiB, fast to execute
+    with Sandbox(timeout_s=20) as s:
+        r = s.run_code(code)
+    assert r.success and r.stdout.strip() == "big-ok"
+
+
+@integration
+def test_user_exception_is_not_a_fault():
+    with Sandbox(timeout_s=20) as s:
+        r = s.run_code("raise ValueError('boom')")
+    assert r.fault is None and r.exit_code != 0 and "ValueError" in r.stderr
+
+
+@integration
+def test_default_box_is_network_isolated():
+    with Sandbox(timeout_s=20) as s:
+        r = s.run_code(
+            "import socket; socket.setdefaulttimeout(4); "
+            "socket.socket().connect(('1.1.1.1', 53)); print('CONNECTED')"
+        )
+    assert not r.success and "CONNECTED" not in r.stdout
+
+
+@integration
+def test_host_secret_env_does_not_leak(monkeypatch):
+    monkeypatch.setenv("HOST_SECRET", "super-secret-token-xyz")
+    with Sandbox(timeout_s=20) as s:
+        r = s.run_code("import os; print(os.environ.get('HOST_SECRET', 'ABSENT'))")
+    assert "super-secret" not in r.stdout and "ABSENT" in r.stdout
+
+
+@integration
+def test_one_shot_run_code_helper():
+    r = kern.run_code("print(6 * 7)", timeout_s=20)
+    assert r.stdout.strip() == "42" and r.success
+
+
+@integration
+def test_workspace_is_deleted_on_exit_when_owned():
+    holder = {}
+    with Sandbox(timeout_s=20) as s:
+        holder["ws"] = s._ws
+        s.write_file("a.txt", "x")
+        assert os.path.exists(os.path.join(s._ws, "a.txt"))
+    assert not os.path.exists(holder["ws"])  # temp workspace cleaned up