Tool Execution Sandbox

What it is

A confined environment in which a tool's work actually runs, chosen so that what happens inside it cannot reach the host, the other tenants, or anything the call was not meant to touch. It is the mechanism answer to a specific problem: some tools execute code that nobody reviewed — generated by a model, supplied by a user, or shipped by a third party — and the process running it needs a boundary with defined properties rather than the ambient privileges of whatever started it.

Why it matters

A tool that runs arbitrary code is indistinguishable, from the operating system's point of view, from an attacker with a shell. The code may have been produced by a model that read an instruction hidden in a document, and the host process typically has a service account, network reach into internal systems, and environment variables holding credentials. Isolation is what turns "the agent was tricked into writing a malicious script" from a breach into a failed call with a useless outcome. It is also what makes resource exhaustion survivable, since an unbounded loop inside a boundary is a dead sandbox rather than a dead node.

Key decisions

• Strength of the boundary against its startup cost. Namespaces and a seccomp profile start in milliseconds and share a kernel; a virtual machine does not share a kernel and starts far more slowly. The right answer depends on whether the code inside is hostile or merely untested.
• Lifetime. A fresh environment per call is the only shape with no cross-call leakage and the most expensive; a pool of warm environments is fast and requires a reset you can defend; a persistent workspace per session is what iterative work actually needs and holds state that must then be isolated per tenant.
• What is inside. A minimal image reduces attack surface and breaks tools that expected a package to be there; a rich image is convenient and is also a library of useful primitives for anyone who gets in.
• Resource ceilings — processes, memory, file descriptors, disk, wall-clock — and what happens on breach: kill, throttle, or fail the call with a diagnosable message.
• How data gets in and out. A mounted path, a streamed payload, or an explicit artefact store each have different leakage properties, and the output path is the one that matters most.
• Whether any credential is ever present inside the boundary. Usually the correct answer is none, with privileged operations brokered by a component outside it.
• What the sandbox can reach on the network, including the host's own metadata and management interfaces, which are reachable by default in most deployments.

Failure modes

• A standard container is treated as a boundary against hostile code; a kernel vulnerability or a permissive capability set then makes it a boundary against mistakes only.
• A pooled environment is reused without a complete reset, and one tenant's files, caches, or shell history are readable by the next.
• The instance metadata service is reachable from inside, so code in the sandbox mints credentials for the host's identity and leaves with them.
• Egress is restricted to block the public internet while every internal service remains reachable, which is the half of the network that matters.
• A fork bomb or a disk-filling loop exhausts a resource that was limited per container but shared per node, taking down unrelated workloads.
• Results are exfiltrated through a channel nobody counted as network access — a DNS lookup, an error message, a filename written to a shared volume.
• Cold start dominates the latency budget, so someone adds a fast path that runs "trusted" tools outside the boundary, and the exception becomes the common case.
• The environment image drifts from what tools expect, and failures appear as mysterious import errors attributed to the model rather than to the platform.
• Logs and artefacts produced inside are copied out and parsed by a privileged process that trusts their contents.

Related capabilities

• Tool Permission Management — decides what may run before isolation contains it
• Credential and Secret Management — why nothing sensitive belongs inside the boundary
• Tool Timeout and Retry — the wall-clock ceiling enforced here
• MCP Server — a locally spawned server is a process that needs this treatment
• Tool Result Normalization — handles output leaving the boundary

Applies: Production readiness · Design questions