Allowing an AI agent to write and run its own code makes it incredibly powerful. But executing untrusted, machine-generated code is a major security risk. An agent code execution sandbox is an essential tool for managing this risk. It provides an isolated environment that limits what the code can do, protecting your main application and infrastructure from harm.

This guide explains how to design and configure a secure sandbox, moving from core concepts to a practical, step-by-step example.

Key takeaways

  • Separate Planes: Always run agent-generated code in an execution environment that is isolated from your orchestration logic, production credentials, and host system (Source).
  • Isolation is Key: Choose an isolation boundary—typically containers or microVMs—to limit the code's access to processes, filesystems, and the network (Source).
  • Apply Least Privilege: Configure strict resource limits (CPU, memory, time), block network access by default, use non-root users, and mount only the required files as read-only where possible.
  • Sandboxing is Not a Silver Bullet: A sandbox limits the blast radius but doesn't eliminate all risk. It's one layer in a defense-in-depth strategy that must also include input/output validation, monitoring, and narrow credential brokering (Source).
  • Manage State Deliberately: Decide between ephemeral sandboxes (clean slate per task) and persistent ones (state survives across steps). Persistent state requires explicit cleanup, access control, and lifecycle policies (Source).

How does an agent code execution sandbox work?

An agent code execution sandbox works by creating a temporary, restricted environment to run code, separate from the main application. This architecture is built on the principle of separating the trusted "Agent Plane," which handles orchestration and secrets, from the untrusted "Execution Plane," where the code actually runs. This separation ensures that even if the agent's code is malicious or buggy, its impact is confined within the sandbox walls.

Here is the step-by-step process:

  1. Provision Runtime: The orchestrator receives a request to execute code from the agent. It provisions a new, isolated runtime environment, like a Docker container or a microVM, based on a predefined template.
  2. Transfer Code and Data: The orchestrator sends the code snippet and any necessary input files into the sandbox. These files are typically mounted into a specific working directory.
  3. Execute Code: The code runs inside the isolated environment. The sandbox runtime enforces strict rules defined by its configuration. It limits how much CPU and memory the code can use, which files it can see, and whether it can make network calls.
  4. Capture Results: The sandbox captures the outputs of the execution. This includes the standard output (stdout), standard error (stderr), exit code, and any new files created in a designated output directory (Source).
  5. Return Results: The captured results are sent back to the agent's orchestrator. The orchestrator can then pass this information back to the LLM for the next step in its reasoning process.
  6. Terminate or Reset: Once the execution is complete, the sandbox environment is destroyed or reset to a clean state. This prevents any changes or installed malware from affecting subsequent tasks.

This entire process prevents the agent's code from ever directly accessing the host system, its files, or its credentials.

What are the key isolation technologies? Container vs. MicroVM

The most important decision in designing a sandbox is choosing the isolation technology. Containers and microVMs (micro-virtual machines) are the two most common approaches, each with distinct security and performance trade-offs. A microVM is a lightweight virtual machine designed for fast startup and minimal resource footprint.

Your choice depends on your threat model. If you assume the code is actively hostile and will try to escape its confinement, a microVM provides a much stronger security boundary (Source). If you need maximum speed for code from trusted users, containers are often a sufficient and more efficient choice.

Feature Containers (e.g., Docker) MicroVMs (e.g., Firecracker)
Isolation Boundary Shares host OS kernel Provides a dedicated guest kernel
Security Weaker; a kernel vulnerability can lead to escape. Stronger; provides hardware-virtualized isolation.
Startup Time Fast (milliseconds to seconds) Slower (hundreds of milliseconds to seconds)
Resource Overhead Low (minimal memory and CPU) Higher (requires memory for guest kernel)
Best For Trusted or semi-trusted code, high-performance needs. Untrusted, multi-tenant workloads, high-security needs.

While some systems use language-level restrictions, these are often fragile and can be bypassed. OS-level process isolation using containers or virtualization with microVMs provides a more robust and reliable security guarantee.

How do you configure a secure sandbox? A worked example

To configure a secure agent code execution sandbox, you must apply the principle of least privilege. This means giving the code only the exact permissions and resources it needs to complete its task, and nothing more. Using containers, we can enforce these limits with specific command-line flags.

Let's walk through an illustrative example.

Goal: Allow an AI agent to run a Python script (analyze.py) that reads an input file (data.csv) and generates an output file (plot.png). The code should not be able to access the network or any other files on the host system.

Step 1: Create a Minimal Docker Image

First, define a minimal environment. The Dockerfile below creates a new, non-root user appuser and installs only the necessary Python library.

Dockerfile
# Use a minimal base image
FROM python:3.11-slim

# Create a non-root user and a working directory
RUN useradd -ms /bin/bash appuser
WORKDIR /app
RUN chown appuser:appuser /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Switch to the non-root user
USER appuser

This ensures the code inside the container doesn't run with root privileges.

Step 2: Run the Container with Security Flags

Next, use the docker run command with flags that enforce strict security policies.

Bash
docker run \
  --rm \
  --user=appuser \
  --network=none \
  --memory=256m \
  --cpus=0.5 \
  --pids-limit=100 \
  --cap-drop=ALL \
  --security-opt seccomp=default \
  -v "$(pwd)/data.csv:/app/data.csv:ro" \
  -v "$(pwd)/output:/app/output" \
  my-python-sandbox \
  python analyze.py

Let's break down what each flag does:

  • --rm: Automatically removes the container when it exits, ensuring a clean slate for the next run.
  • --user=appuser: Runs the process as the non-privileged user we created.
  • --network=none: Disables all networking, preventing any data exfiltration or access to internal services (Source).
  • --memory=256m and --cpus=0.5: Limit the container to 256MB of RAM and half of a CPU core, preventing denial-of-service attacks (Source).
  • --pids-limit=100: Restricts the number of concurrent processes to 100 to prevent fork bombs.
  • --cap-drop=ALL: Drops all Linux capabilities, removing rights like changing file ownership or binding to privileged ports, even if running as root (which we are not).
  • --security-opt seccomp=default: Applies the default seccomp profile, which blocks a list of dangerous system calls to reduce the kernel's attack surface.
  • -v "$(pwd)/data.csv:/app/data.csv:ro": Mounts the input file data.csv into the container's /app directory as read-only (:ro). The code can read it but cannot modify or delete the original.
  • -v "$(pwd)/output:/app/output": Mounts a local output directory as a writable volume where the script can save its plot.png result.

This configuration can be extended to control other resources. An external process can enforce an execution time limit by terminating the container after a timeout. Disk space and output size can be managed with storage driver options (like --storage-opt size=1G) or by monitoring the output directory's size.

Ephemeral vs. persistent sandboxes: Managing state and lifecycle

When you design an agent code execution sandbox, you must decide how to manage its state between tasks. This choice leads to two main models: ephemeral and persistent sandboxes.

An ephemeral sandbox is created for a single task and destroyed immediately after. This is the simplest and safest model. Each execution starts with a clean, known state, which prevents malicious code or accidental changes from one task from affecting the next (Source). Think of it as using a fresh sheet of paper for every calculation.

A persistent sandbox maintains its state across multiple executions within a single agent session. Files created, packages installed, or variables set in one step are available in the next. This is essential for complex, multi-step workflows, like debugging code or analyzing a dataset interactively (Source). This is like working on a single project notebook over time.

However, persistence introduces security risks. A malicious dependency installed in step one could steal data in step two. Therefore, persistent sandboxes require careful management:

  • Session Ownership: Ensure one user's persistent sandbox is never accessible to another.
  • Idle Timeouts: Automatically terminate sandboxes that have been idle for too long to prevent resource waste and reduce the attack surface.
  • Cleanup Policies: Have a clear process for deleting the sandbox and its associated storage when the user's session ends (Source).

Our recommendation: Use ephemeral sandboxes by default. Only opt for a persistent sandbox when the agent's workflow explicitly requires state to be carried between steps, and be sure to implement strict lifecycle and access controls.

What common security threats should you plan for?

A sandbox is a containment strategy, designed to limit the damage from a security breach. Building an effective one requires understanding the threats you're defending against.

Here is a threat model for an agent code execution sandbox:

  • Host Escape: Malicious code exploits a vulnerability in the container runtime or the host OS kernel to break out of the sandbox and gain control of the host machine.
    • Mitigation: Use microVMs for a stronger boundary, keep all system software patched, and use security profiles like seccomp to restrict available system calls.
  • Data Exfiltration: The code reads sensitive data mounted into the sandbox and sends it to an attacker's server.
    • Mitigation: Mount the absolute minimum data required and set it to read-only whenever possible. Block all outbound network traffic by default, using an allowlist for any necessary connections (Source).
  • Denial of Service (DoS): The code deliberately consumes all available CPU, memory, or disk space, crashing the host or impacting other sandboxes.
    • Mitigation: Enforce strict resource limits (CPU, memory, process count) and execution timeouts.
  • Credential Theft: The code searches the environment for API keys, service account tokens, or other secrets and uses them to access other systems.
    • Mitigation: Never mount unrestricted credentials. Instead, use a brokered proxy service that exposes narrowly-scoped actions to the agent.
  • Supply-Chain Attack: The code uses a package manager like pip or npm to download and install a malicious dependency. This is a common vector for attacks where agents are manipulated into installing malicious packages.
    • Mitigation: Restrict or block network access to package repositories. If package installation is necessary, use a curated set of vetted packages or scan them for vulnerabilities before use (Source).

When is a sandbox not enough?

A sandbox is a powerful and necessary tool, but it's not a complete security solution. It's a containment control, not a prevention control. It limits the blast radius of a malicious action but doesn't stop the action from being attempted in the first place.

Here are situations where a sandbox alone is insufficient:

  • Destructive Actions: If an agent needs to perform a high-stakes action, like deleting a production database or deploying code, a sandbox won't ask "should this happen?" It will only execute the command within its walls. For such actions, you still need an approval workflow, where a human or a separate policy engine must explicitly authorize the command before it is sent to the sandbox (Source).
  • Business Logic Flaws: A sandbox cannot understand the context of your application. An agent might generate code that is perfectly safe from a system perspective but implements a flawed business rule, like applying the wrong discount to a customer. This type of error must be caught through code review, testing, and application-level validation.
  • Data Privacy Violations: If you mount personally identifiable information (PII) into a sandbox, the sandbox can't prevent the agent's code from misusing it. The responsibility for data governance—ensuring only appropriate data enters the sandbox—lies outside the sandbox itself.

Security requires defense in depth. An agent code execution sandbox is a critical layer for isolating untrusted code, but it must be combined with strong authentication, authorization, input validation, monitoring, and, for critical operations, a human in the loop.

What to learn next

  • How does sandboxing fit into a complete agent security strategy? While sandboxing contains malicious code, a robust system also requires defending against other threats. Learn more about building a complete agent security strategy that covers the entire attack surface.
  • How can you test if an agent is safe and effective? A secure sandbox is one part of the puzzle. Our practical guide to AI agent evaluation explains how to implement rigorous methods to test an agent's safety, correctness, and performance.
  • What new challenges appear in multi-agent systems? When multiple agents collaborate, the potential for complex security vulnerabilities increases. Read about these security challenges in multi-agent systems to learn about secure communication protocols.

Sources and further reading