sandboxing_agents v1.0.0

name: "sandboxing_agents" description: "Sandbox AI agent code execution: choose the right isolation tier (containers, gVisor, microVMs), lock down Docker with filesystem, network, and resource policy, and build a command gateway with approval boundaries. Triggers when an agent needs to run generated or untrusted code, or when hardening an agent's shell tool." metadata: { "includeInPrompt": true }

Sandboxing Agents

Purpose

Give an agent a place to run code where mistakes and prompt injections cannot escape. You design the isolation boundary, the filesystem scope, the network policy, and the resource limits, then verify the whole thing with a hostile dry run before any real task runs inside it.

Workflow

1. Threat model the task. Write down what the agent must touch (files, domains, services) and what it must never touch (host files, credentials, the internet at large, production data). If you cannot name both lists, stop. You are not ready to build the sandbox.
2. Pick the isolation tier. Match the strength of the boundary to how untrusted the code is:

• Trusted, team-written helper scripts: a hardened container is fine.
• Agent running code you reviewed: hardened container plus a command gateway and approval policy.
• Agent running code an LLM just generated: you need a boundary that survives a kernel bug. Use a microVM (Firecracker, Kata) or a user-space kernel (gVisor). A plain container shares the host kernel, and a kernel CVE in one workload reaches every workload on the node.
• Regulated data (PII, financial, health): confidential computing on top of a microVM. See references/isolation-tiers.md for the tradeoffs.

1. Lock the filesystem. Mount only the task's workspace, read/write. Everything else is read-only or absent. Never mount the host home directory, SSH material, .env files, cloud credentials, or the Docker socket. Run as an unprivileged UID. Read-only root filesystem, with a bounded tmpfs for /tmp if the workload needs scratch space.
2. Kill the network by default. No outbound access unless the task proves it needs it. When access is needed, route it through a host-side proxy that enforces a domain allowlist (the pattern Anthropic uses for Claude Code's sandbox: traffic goes through a Unix domain socket to a proxy outside the sandbox, and the proxy decides which domains are reachable). Apply the network policy to every tool surface, not just the shell tool: file readers, browser tools, and MCP servers get the same default-deny. Cover the setup phase too. A platform that blocks the agent's browsing but leaves npm install wide open hands attackers a hole before the agent even starts working.
3. Set hard resource limits. CPU quota, memory cap, PID limit (fork bombs are cheap to write), a wall-clock timeout on every run, and caps on input and output size. A recursive script an agent wrote for itself is the failure mode you are defending against, and it happens more often than an attack.
4. Put a gateway in front of execution. The agent submits an argv array, never a shell string; the gateway invokes it without a shell. The gateway checks each request against the task's scope and timeout before running it, resolves file paths with realpath and rejects anything outside the workspace, and applies a failure contract: non-zero exit stops the workflow, stderr gets summarized before it feeds back to the model, the timeout is treated as a failure (not as a reason to retry with a bigger scope), and generated files are listed before anything is exported. There is never a host-shell fallback if the sandbox is unavailable. The run fails closed.
5. Draw approval boundaries for the risky edges. Some actions should stop for a human even inside a good sandbox: destructive commands, writes to external systems (git pushes, database changes, webhooks, email), reads of sensitive paths, execution against production data, browser navigation to unknown domains. Tie approvals to capabilities and targets, not to how the agent words the request. And track cumulative impact across the whole session: a per-call $50 refund limit is meaningless if the agent can call a $20 refund six times.
6. Treat the image as a trust boundary. Pin base images by digest, scan them, sign them, and never let the runtime pull implicitly. An image that changes under you is a new boundary you did not approve.
7. Log everything, redact secrets. Every execution records the command, image, limits, exit code, and cleanup status. Secrets never appear in logs. Alert on outbound connections that bypass the proxy: a direct connection from an agent process is a policy violation, and it reads exactly like exfiltration.
8. Hostile dry run before go-live. Write a script that tries to read outside the workspace, phone home, fork-bomb, mount the socket, and curl a disallowed domain. Every attempt must fail. Only then does a real task run inside.

Output Contract

A sandbox spec the operator can audit: (1) the isolation tier chosen and why, (2) the exact filesystem scope and mounts, (3) the network policy as plain sentences ("Scripts cannot reach the internet", "Browser may visit these three sites"), (4) the resource limits table, (5) the approval boundaries and cumulative budgets, (6) the image pinning and scan status, (7) the gateway's failure contract, (8) the dry-run results with every attack attempt and its outcome. If any item is missing, the sandbox is not done.

Operating Rules

1. Policy lives in infrastructure, never in the model. A sandbox that depends on the agent making the right security decision every time is not a sandbox.
2. Default deny on everything: filesystem writes, network, syscalls, mounts. Each grant needs a reason and a scope.
3. Fail closed. Unavailable sandbox, missing image, policy check timeout: the run stops, it never falls through to the host.
4. The escape hatch is explicit and never autonomous. A debug backend that runs on the host exists only if an operator chooses it by hand; the agent's planner may not select it on its own.
5. Parallel tasks get separate workspaces that cannot see each other.
6. Clean up every run: destroy the container, wipe the scratch space, close the logs. A leaked container from last Tuesday is a foothold.
7. Review the scope whenever the agent's task set changes. A filesystem grant that made sense last month is an attacker's redirect target today.
8. Never claim a container is a perfect security boundary. State what it survives (container escape attempts within the pinned runtime) and what it does not (host kernel CVE).