# Sandboxed execution

> Tools run in a hardened, isolated pod — non-root, read-only root filesystem, no ambient token — as argv, never a shell.

Source: https://openap.org/docs/sandboxed-execution

A validated tool still has to *run* somewhere, and where it runs is a hardened, isolated sandbox — not
the agent's own process. The pod is stripped of ambient authority, and the tool is executed as an argv array,
never through a shell.

## A pod with nothing lying around

Sandbox (and runner) pods are locked down by default: they run **non-root**, with a **read-only root
filesystem**, **all Linux capabilities dropped**, privilege escalation disabled, and the default seccomp
profile applied. Crucially, the sandbox has **no ambient Kubernetes token** — the service-account token isn't
mounted — so a tool can't turn around and call the cluster API with the pod's identity. Working directories are
small in-memory scratch space. Sandboxes run as hardened pods; setting a runtime class such as `kata-fc` on the
sandbox class gives micro-VM isolation where the cluster provides it.

## Argv, never a shell

The tool's command is an **argv array** — an explicit list of arguments — POSTed to the pod's exec endpoint,
never a string handed to `sh -c`. A filename argument like `; rm -rf /` is an inert positional argument, not a
new command, because there's no shell to interpret it. This is the execution-time half of the
[toolspec](https://openap.org/docs/toolspec-validation)'s promise: what was declared is exactly what runs.

## Pluggable backends

Where the sandbox lives is itself a seam. The default `pod` backend builds a hardened pod directly; an
`agent-sandbox` backend drives an upstream sandbox controller. Both present the same workspace, so an agent's
tools don't care which is in use — and an unrecognized backend fails the class closed rather than falling back.

## Contained on the network

Each session gets its own **NetworkPolicy** (on by default). The runner's egress is limited to what it
genuinely needs — DNS, the in-cluster bus and control plane, this session's own sidecars, and outbound HTTPS —
and the sandbox's egress follows the class's declared network mode, **failing closed to deny-all** if the class
doesn't say otherwise.

> **Tip: Hostname allowlists need a DNS-aware CNI**
>
> A class can record an allowlist of hostnames its sandbox may reach, but plain Kubernetes NetworkPolicy can
> only express IP ranges, so that list is *recorded, not enforced* at L3/L4. Enforcing egress by
> hostname is the cluster operator's job — a DNS-aware network plugin (Cilium, Calico) consuming the recorded
> allowlist.
