Use when LLM-invoked tools execute code, touch the filesystem, or make network calls — and you need to bound their blast radius. Apply when designing the isolation boundary for tool execution in an agent harness. Covers filesystem jails, network egress controls, exec sandboxes (containers, gVisor, firecracker, seatbelt/landlock), capability-scoped credentials, and the difference between safety sandboxing and security sandboxing.
Use when LLM-invoked tools execute code, touch the filesystem, or make network calls — and you need to bound their blast radius. Apply when designing the isolation boundary for tool execution in an agent harness. Covers filesystem jails, network egress controls, exec sandboxes (containers, gVisor, firecracker, seatbelt/landlock), capability-scoped credentials, and the difference between safety sandboxing and security sandboxing.
Tool Sandboxing
Pain Signals — You Need This Pattern When:
Tools can execute arbitrary code (Bash, python, node -e) and a hallucinated command could damage the host
Tools fetch URLs, and a prompt-injected URL could exfiltrate secrets or pivot internally
Tools have ambient credentials (cloud SDK, kubeconfig) that grant far more than the task requires
Untrusted input (user uploads, web pages, third-party APIs) reaches the LLM and shapes tool calls — prompt injection is realistic
The harness runs as a service for multiple users; one user's session must not affect another's
Two distinct goals. Safety sandboxing prevents accidents (rm -rf typos). Security sandboxing prevents adversaries (prompt injection driving exfiltration). Same mechanisms, different threat models — and security sandboxing is strictly harder. If your threat model includes an attacker, accept that defense-in-depth is required.
Core Principle
Treat the tool layer as untrusted by default. The trust boundary is between the harness core (your code, your decisions) and tool execution (model-driven, prompt-injectable). Everything the model can cause to happen must be bounded explicitly.
Enforce at network namespace / firewall, not in the tool. In-tool URL validation is bypassable (DNS rebinding, redirects).
Exec Isolation
For tools that run code:
Mechanism
When
Subprocess with rlimits
Single-user dev tool, low risk
Container per call
Production, moderate risk
MicroVM per call
Untrusted code (CI runners, sandbox-as-a-service)
WASM
Pure-compute tools, no syscall surface
Per-call vs per-session containers: per-call gives clean state but high startup cost; per-session is cheaper but accumulates state. Default to per-session with resettable workspace; per-call for high-risk tools.
Resource caps are non-optional:
cpu: bounded (cgroup quota)
memory: bounded (OOM kill)
pids: bounded (no fork bombs)
disk: bounded (no fill-the-disk)
time: wall-clock timeout
Credential Scoping
The sandbox is only as good as the credentials inside it.
No ambient cloud auth. No ~/.aws, no instance metadata access, no kube-context.
Pass scoped tokens explicitly. Tool that calls GitHub gets a token with the minimum repo scope, not the user's full PAT.
Short TTL. Tokens expire in minutes, not hours.
Per-session or per-call issuance. Audit which call used which token.
Never log credentials. Redact before transcript and telemetry.
Default-deny allowlist, block metadata, DNS pinning
Auth
Limit user-context
No ambient creds, scoped short-lived tokens
Resources
Reasonable caps
Hard caps + monitoring + alarm
Validation
Trust the harness
Assume harness can be tricked; sandbox catches what gates miss
If the threat model has an attacker, you are in security mode. Don't design as if it's safety mode and hope.
Escape Hatches
Some tools genuinely need elevated capability (deployment, infra changes). Don't widen the sandbox; build a narrow trapdoor.
Operation-specific (not blanket)
Logged with full context
Approved at issuance, not at use
Time-limited
Revocable mid-session
Common Pitfalls
Pitfall
Symptom
Fix
Path validation in user-space tool
TOCTOU race or symlink bypass
Kernel-level jail
Sandbox without egress control
Exfiltration channel via curl
Default-deny network
Cloud metadata reachable
IMDS attack works
Block 169.254.169.254 explicitly
Ambient creds in env
Compromise = full account
Scoped tokens passed per call
Sandbox shared across users
Cross-tenant leak
Per-session isolation
Fork bomb crashes host
DoS
pids cgroup limit
Same sandbox per session, never reset
State accumulates between tasks
Reset workspace at task boundary
In-tool URL allowlist
Bypassable via redirect
Network-layer enforcement
"Trusted" tools skip sandbox
One bad tool defeats the boundary
All tools in sandbox; trusted ones get more capability inside the sandbox
When NOT to Use (Heavy Sandboxing)
Local single-user dev tool, no untrusted input. Subprocess + permission gates may be enough.
Tools are pure compute (math, format, parse). Restrict syscalls instead of full container.
Read-only research agents with no shell, no fs writes, no auth tokens.
But "we trust our users" is not a reason to skip the egress allowlist if untrusted input ever reaches the model. Web pages, PR descriptions, and email bodies are untrusted input.
Design Checklist
Threat model explicit: safety only, or security (attacker in scope)
Trust boundary documented; tool execution treated as untrusted past the boundary
Filesystem jail: writable workspace, system paths invisible, no symlink escape
Network: default-deny with allowlist; metadata services blocked; DNS controlled
No ambient credentials in sandbox; scoped short-lived tokens issued per call
Resource caps: cpu, memory, pids, disk, wall-clock — all enforced
Per-session isolation; sessions cannot see each other's workspace or processes
Tool args and credentials redacted before transcript and telemetry
