core.sandbox
core.sandbox
Zone A — sandboxed code execution: same power, no reach (BUILD-SPEC §11, Invariant 4).
Executed code runs in an ephemeral, network-off, vault-less, non-root, resource-limited
container (rootless Podman) and returns DATA, never actions. The isolation profile is built
into the podman argv in policy.py so it is verifiable by construction. A warm pool avoids
cold start; the broker is the thin facade agents call.
RUNTIMES = {'python': ('python:3.12-slim', ['python3', '-']), 'bash': ('bash:5', ['bash', '-s']), 'node': ('node:22-slim', ['node', '-'])}
module-attribute
SANDBOX_INPUT_DIR = '/tmp/input'
module-attribute
ExecutionBroker
dataclass
runner
instance-attribute
policy
instance-attribute
pool = None
class-attribute
instance-attribute
telemetry = None
class-attribute
instance-attribute
max_concurrency = 1
class-attribute
instance-attribute
run(spec)
shutdown()
SandboxPolicy
dataclass
image = None
class-attribute
instance-attribute
user = '65534:65534'
class-attribute
instance-attribute
seccomp_profile = None
class-attribute
instance-attribute
tmpfs_size = '64m'
class-attribute
instance-attribute
extra = ()
class-attribute
instance-attribute
SandboxBusyError
Bases: RuntimeError
All warm sandboxes are in use — the concurrency cap (Invariant 8) was reached.
WarmPool
dataclass
runner
instance-attribute
policy
instance-attribute
limits
instance-attribute
size = 1
class-attribute
instance-attribute
language = 'python'
class-attribute
instance-attribute
prewarm()
acquire()
release(container, *, healthy=True)
shutdown()
stats()
PodmanRunner
dataclass
binary = 'podman'
class-attribute
instance-attribute
available()
Usable, not merely installed: the binary must exist AND the (rootless) Podman
service must answer. On macOS podman can be on PATH while the machine is stopped.
run_once(spec, policy)
start(policy, limits, image)
exec_in(container, spec)
reset(container)
destroy(container)
RoutingRunner
dataclass
Picks the substrate per job: the WASM pure-compute path for python-with-no-network WHEN it is actually available, else Podman (BUILD-SPEC §11 / roadmap E2). Fail-safe by default — with no WASI module placed, every job routes to the verified Podman substrate.
wasm
instance-attribute
podman
instance-attribute
available()
run_once(spec, policy)
start(policy, limits, image)
exec_in(container, spec)
reset(container)
destroy(container)
SandboxRunner
Bases: Protocol
available()
run_once(spec, policy)
start(policy, limits, image)
exec_in(container, spec)
reset(container)
destroy(container)
WasmRunner
dataclass
Pure-compute substrate (BUILD-SPEC §11): a WASI build of CPython run under wasmtime.
The strongest isolation we have — isolation BY ABSENCE OF SYSCALL IMPORTS rather than by
dropped capabilities: a wasm guest can touch only what the host explicitly grants through
WASI, and we grant nothing but stdio (no sock_*, no host preopens) → no network, no host
fs, no vault, structurally, the same powerless guarantee as Podman but enforced by the
runtime rather than the kernel. Preferred for pure computation; Podman remains the substrate
for anything needing a fuller OS.
Activation is an owner step (a heavy artifact, like the Podman libs image): pip install
wasmtime (done) AND a WASI CPython at wasm_module (a python.wasm). Until both are
present, available() is False and the RoutingRunner falls back to Podman — fail-closed,
never a silent wrong-substrate run. The execution path below is real wasmtime; it activates
the moment the module is placed (runbook → "WASM sandbox").
wasm_module = None
class-attribute
instance-attribute
fuel = None
class-attribute
instance-attribute
available()
run_once(spec, policy)
start(policy, limits, image)
exec_in(container, spec)
reset(container)
destroy(container)
WasmUnavailableError
Bases: RuntimeError
The WASM runner was asked to run but wasmtime and/or a WASI python module is not placed.
ExecResult
dataclass
stdout
instance-attribute
stderr
instance-attribute
exit_code
instance-attribute
timed_out = False
class-attribute
instance-attribute
duration_s = 0.0
class-attribute
instance-attribute
truncated = False
class-attribute
instance-attribute
ok
property
ExecSpec
dataclass
code
instance-attribute
language = 'python'
class-attribute
instance-attribute
timeout_s = DEFAULT_TIMEOUT_S
class-attribute
instance-attribute
limits = field(default_factory=Limits)
class-attribute
instance-attribute
network = Network.NONE
class-attribute
instance-attribute
env = field(default_factory=dict)
class-attribute
instance-attribute
inputs = field(default_factory=dict)
class-attribute
instance-attribute
Limits
dataclass
memory = '256m'
class-attribute
instance-attribute
cpus = 1.0
class-attribute
instance-attribute
pids = 128
class-attribute
instance-attribute
Network
Bases: StrEnum
NONE = 'none'
class-attribute
instance-attribute
build_broker(config=None, *, telemetry=None)
Wire a broker from config: the configured runtime + a warm pool sized to the concurrency cap.
build_run_argv(spec, policy=DEFAULT_POLICY, *, name=None)
Ephemeral podman run --rm: isolate, feed the code on stdin, capture output, vanish.
build_warm_argv(policy, *, name, image, limits)
Start a long-lived, idle, fully-isolated container for the warm pool. It holds no
job; code is later podman exec'd into its scratch tmpfs and run.
compose_program(spec)
The exact program piped to the interpreter on stdin: the user's code, prefixed (when
inputs are present) with a preamble that materializes each input to /tmp/input/<name>.
The data travels IN-BAND on stdin, NOT via a host bind mount — so the structural guarantee that nothing from the host (the vault, indeed the whole host fs) is reachable is unchanged (Invariant 4). Supported for python only (the data-analysis target); requesting inputs for another language is refused rather than silently dropped.
build_runner(runtime, *, binary='podman', wasm_module=None)
broker
Execution broker — the thin facade agents use to run code (BUILD-SPEC §11, Invariant 4).
run(spec) -> ExecResult returns data, never actions. It routes through the warm pool
(reusing a ready sandbox) when the job's language matches the pooled image, else an ephemeral
container; it enforces the concurrency cap (Invariant 8) and logs every execution —
language, network mode, timeout — to telemetry so any (future) network grant is auditable
(§11). Phase 4 runs network-off only.
ExecutionBroker
dataclass
runner
instance-attribute
policy
instance-attribute
pool = None
class-attribute
instance-attribute
telemetry = None
class-attribute
instance-attribute
max_concurrency = 1
class-attribute
instance-attribute
run(spec)
shutdown()
build_broker(config=None, *, telemetry=None)
Wire a broker from config: the configured runtime + a warm pool sized to the concurrency cap.
policy
The sandbox security profile, built into the podman argv (BUILD-SPEC §11, Invariant 4).
These are PURE functions so the isolation is verifiable by construction, not just empirically:
a test can assert the argv carries --network=none, --read-only, --cap-drop=ALL,
non-root --user, the resource limits, and — critically — that it mounts nothing from the
host, so the private vault (indeed the whole host filesystem) is structurally unreachable.
Code is delivered on stdin to the interpreter, so no bind mount is ever needed.
SANDBOX_INPUT_DIR = '/tmp/input'
module-attribute
RUNTIMES = {'python': ('python:3.12-slim', ['python3', '-']), 'bash': ('bash:5', ['bash', '-s']), 'node': ('node:22-slim', ['node', '-'])}
module-attribute
DEFAULT_POLICY = SandboxPolicy()
module-attribute
SandboxPolicy
dataclass
image = None
class-attribute
instance-attribute
user = '65534:65534'
class-attribute
instance-attribute
seccomp_profile = None
class-attribute
instance-attribute
tmpfs_size = '64m'
class-attribute
instance-attribute
extra = ()
class-attribute
instance-attribute
compose_program(spec)
The exact program piped to the interpreter on stdin: the user's code, prefixed (when
inputs are present) with a preamble that materializes each input to /tmp/input/<name>.
The data travels IN-BAND on stdin, NOT via a host bind mount — so the structural guarantee that nothing from the host (the vault, indeed the whole host fs) is reachable is unchanged (Invariant 4). Supported for python only (the data-analysis target); requesting inputs for another language is refused rather than silently dropped.
runtime_for(language)
image_for(language, policy)
build_run_argv(spec, policy=DEFAULT_POLICY, *, name=None)
Ephemeral podman run --rm: isolate, feed the code on stdin, capture output, vanish.
build_warm_argv(policy, *, name, image, limits)
Start a long-lived, idle, fully-isolated container for the warm pool. It holds no
job; code is later podman exec'd into its scratch tmpfs and run.
pool
Warm pool of ready sandboxes (BUILD-SPEC §11, §5).
Cold-starting a container per execution is slow, so we keep a small pool warm and reuse it. Pool size is the concurrency cap — we never hold more sandboxes than the RAM ceiling allows (Invariant 8). A container that overran its timeout is discarded, never reused (it may be wedged); a healthy one is reset (its scratch tmpfs cleared) and returned to the pool.
SandboxBusyError
Bases: RuntimeError
All warm sandboxes are in use — the concurrency cap (Invariant 8) was reached.
WarmPool
dataclass
runner
instance-attribute
policy
instance-attribute
limits
instance-attribute
size = 1
class-attribute
instance-attribute
language = 'python'
class-attribute
instance-attribute
prewarm()
acquire()
release(container, *, healthy=True)
shutdown()
stats()
runner
Sandbox runners — the thing that actually executes isolated code (BUILD-SPEC §11).
PodmanRunner is the default substrate (rootless Podman). WasmRunner is the seam for the
pure-compute wasmtime+Pyodide path (the §11 upgrade option); it is declared but not built in
Phase 4. The runner shells out to podman — that is deterministic code acting, never a
model holding a shell (Invariant 3); the executed code itself is powerless (Invariant 4),
which is enforced structurally by the argv in policy.py.
The wall-clock timeout is enforced here via the subprocess timeout; a container that overran is force-removed (and, if pooled, discarded rather than reused).
SandboxRunner
Bases: Protocol
available()
run_once(spec, policy)
start(policy, limits, image)
exec_in(container, spec)
reset(container)
destroy(container)
PodmanRunner
dataclass
binary = 'podman'
class-attribute
instance-attribute
available()
Usable, not merely installed: the binary must exist AND the (rootless) Podman
service must answer. On macOS podman can be on PATH while the machine is stopped.
run_once(spec, policy)
start(policy, limits, image)
exec_in(container, spec)
reset(container)
destroy(container)
WasmUnavailableError
Bases: RuntimeError
The WASM runner was asked to run but wasmtime and/or a WASI python module is not placed.
WasmRunner
dataclass
Pure-compute substrate (BUILD-SPEC §11): a WASI build of CPython run under wasmtime.
The strongest isolation we have — isolation BY ABSENCE OF SYSCALL IMPORTS rather than by
dropped capabilities: a wasm guest can touch only what the host explicitly grants through
WASI, and we grant nothing but stdio (no sock_*, no host preopens) → no network, no host
fs, no vault, structurally, the same powerless guarantee as Podman but enforced by the
runtime rather than the kernel. Preferred for pure computation; Podman remains the substrate
for anything needing a fuller OS.
Activation is an owner step (a heavy artifact, like the Podman libs image): pip install
wasmtime (done) AND a WASI CPython at wasm_module (a python.wasm). Until both are
present, available() is False and the RoutingRunner falls back to Podman — fail-closed,
never a silent wrong-substrate run. The execution path below is real wasmtime; it activates
the moment the module is placed (runbook → "WASM sandbox").
wasm_module = None
class-attribute
instance-attribute
fuel = None
class-attribute
instance-attribute
available()
run_once(spec, policy)
start(policy, limits, image)
exec_in(container, spec)
reset(container)
destroy(container)
RoutingRunner
dataclass
Picks the substrate per job: the WASM pure-compute path for python-with-no-network WHEN it is actually available, else Podman (BUILD-SPEC §11 / roadmap E2). Fail-safe by default — with no WASI module placed, every job routes to the verified Podman substrate.
wasm
instance-attribute
podman
instance-attribute
available()
run_once(spec, policy)
start(policy, limits, image)
exec_in(container, spec)
reset(container)
destroy(container)
build_runner(runtime, *, binary='podman', wasm_module=None)
spec
Execution request/result types for the sandbox (BUILD-SPEC §11, Invariant 4).
Executed code is powerless: it gets no credentials, no network (unless an explicit, logged, per-execution grant — not in Phase 4), and no access to the private vault. It returns data (stdout/stderr/exit code), never actions on the system. Output is capped so a result can never blow the context budget (§13).
DEFAULT_TIMEOUT_S = 10
module-attribute
MAX_TIMEOUT_S = 120
module-attribute
MAX_OUTPUT_BYTES = 64 * 1024
module-attribute
MAX_INPUT_BYTES = 16 * 1024 * 1024
module-attribute
Network
Bases: StrEnum