Containerized Sandboxes for Code-Executing Agent Tools

When an agent can run model-written code, that code must not share the host's filesystem, network, or credentials.

Containers (or stronger: microVMs) give you a practical isolation boundary you can automate on each tool call.

Summary

Run untrusted agent code in a disposable container with a read-only root filesystem, no host network (or tightly allowlisted egress), dropped capabilities, resource limits, and a single mounted work directory that holds only the job inputs.

Recipe

1. Separate the agent host from the executor

The process that talks to the model holds API keys. The process that runs user/model code must not.

2. Build a minimal execution image

Use a slim base, non-root user, no compilers or cloud CLIs unless required, and pin digests in production (verify tags at build).

3. Default-deny network

Start with --network none. Add egress only for documented package or API needs, never "whatever the snippet imports."

4. Mount the least filesystem

Bind-mount a per-job temp directory as the working dir. Do not mount $HOME, Docker socket, cloud metadata paths, or secret volumes.

5. Drop privileges and capabilities

Non-root user, read-only root FS, drop NET_RAW and other caps, no privilege escalation.

6. Cap CPU, memory, PIDs, and wall time

cgroup limits plus a hard kill on timeout stop fork bombs and runaway loops.

7. Capture bounded stdout/stderr

Truncate output before it re-enters the model context. Redact secret-shaped strings if inputs could contain them.

8. Destroy the container after each job

Ephemeral containers prevent persistence across tenants and turns.

Working Example

This pattern shells out to Docker from a tool handler. Swap Podman or a job API as needed; the security shape stays the same.

import subprocess
import tempfile
import textwrap
from pathlib import Path
 
 
def run_in_container(source: str, *, timeout_s: int = 5) -> dict:
    with tempfile.TemporaryDirectory() as td:
        work = Path(td)
        (work / "main.py").write_text(textwrap.dedent(source), encoding="utf-8")
        cmd = [
            "docker", "run", "--rm",
            "--network", "none",
            "--read-only",
            "--tmpfs", "/tmp:rw,noexec,nosuid,size=16m",
            "--user", "65534:65534",
            "--cap-drop", "ALL",
            "--security-opt", "no-new-privileges",
            "--memory", "256m",
            "--cpus", "0.5",
            "--pids-limit", "64",
            "-v", f"{work}:/work:ro",
            "-w", "/work",
            "python:3.12-slim",  # pin digest in prod; verify at build
            "python", "/work/main.py",
        ]
        try:
            proc = subprocess.run(
                cmd, capture_output=True, text=True, timeout=timeout_s + 2
            )
        except subprocess.TimeoutExpired:
            return {"ok": False, "error": "timeout"}
        out = (proc.stdout or "")[:8_000]
        err = (proc.stderr or "")[:2_000]
        return {
            "ok": proc.returncode == 0,
            "stdout": out,
            "stderr": err,
            "code": proc.returncode,
        }
 
 
print(run_in_container("print(sum(range(10)))"))

Wire run_in_container behind your run_python_sandboxed tool; the model only sees the JSON observation, not Docker.

Deep Dive

Why containers beat in-process exec

In-process restricted Python is easy to demo and hard to seal. C extensions, bytecode tricks, and host library bugs share an address space with your secrets.

A container moves the trust boundary to the OS and runtime. Escape risk is not zero, but it is a different class of problem with standard hardening playbooks.

Image design

If snippets need third-party libraries, prebake them into the image or use a reviewed dependency allowlist with offline wheels.

Filesystem policy

• Read-only root forces writes into tmpfs or an explicit data mount.
• Per-job directory isolates tenants; never reuse a dirty workspace.
• Optional output mount can be writable if the tool must return files; scan and size-cap them.

Network policy

--network none is the correct default for pure compute (stats, transforms, puzzles).

If code must call an internal API, prefer:

1. Host-side tool does the HTTP call with scoped credentials, or
2. Container egress via a proxy that allowlists destinations and strips secrets.

Never pass the model's OpenRouter/OpenAI key into the sandbox "so the code can call the LLM."

gVisor, Kata, Firecracker

For multi-tenant SaaS code execution, many teams add a stronger runtime (gVisor, Kata Containers, Firecracker microVMs). Containers alone may be enough for trusted-employee agents; hostile multi-tenant usually needs more.

Observability

Log: job id, image digest, timeout, exit code, bytes of stdout, policy version. Do not log full customer source if policy forbids it; hash or sample instead.

Framework placement

LangGraph, CrewAI, OpenAI Agents SDK, and custom hosts should treat container exec as an ordinary tool with a schema. Isolation is not a framework feature you "turn on"; it is infrastructure you own.

Gotchas

1. Mounting the Docker socket - Equivalent to root on the host. Never expose it to agent code or agent-writable paths.
2. --network host - Defeats isolation for convenience. Avoid.
3. Sharing one long-lived container - Cross-job residue, privilege persistence, noisy neighbors.
4. Root in container with bind mounts - UIDs can still damage mounted host files depending on setup.
5. Unbounded output - Multi-megabyte prints blow context and cost.
6. Pulling images on the hot path - Supply chain and latency risk; pre-pull pinned images.
7. Assuming python:slim is safe forever - Rebuild and patch on a schedule; verify base image policy at build.

Alternatives

FAQs

Related

• Agent Security Basics - first restricted exec pattern
• The Principle of Least Privilege Applied to Agent Tools - design principle
• Network Egress Controls for Agents That Call External Tools - when network is required
• Scoping API Keys and Credentials Passed to an Agent - keep secrets off the sandbox
• Never Grant Blanket Shell Access in Production: What to Do Instead - prefer structured tools
• Security Checklist Before Shipping an Agent to Production
• Agent Security Best Practices

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.