Agent sandbox

Also known as: agent execution sandbox

On this page 7

An agent sandbox is an isolated execution environment in which AI agents run code, shell commands, browsers and other tools under strictly limited access to files, networks, credentials and system resources. It is also called an agent execution sandbox, and its purpose is to let an autonomous system act on a real computer while containing the consequences of errors, misuse or manipulation.

In artificial intelligence, the sandbox has become a standard component of coding agents, computer-use agents and code execution tools. Because a language model can be steered by untrusted input such as prompt injection, the safety of an agent cannot rest on the model behaving well; it must also rest on what the environment allows.

How an agent sandbox contains actions

An agent sandbox works by placing a boundary between the agent’s actions and the host system, so that every command executes inside a constrained space with its own filesystem, process tree and network rules. The agent harness sends tool calls into this space and reads back outputs, while the sandbox enforces limits the model cannot override.

Effective sandboxes combine several independent control layers, because a single mechanism rarely covers every path an agent might take. The table lists the layers most designs include.

LayerWhat it restrictsTypical mechanism
Filesystem isolationWhich files can be read or writtenMount namespaces, read-only mounts, overlays
Process isolationVisibility of other processesPID namespaces, separate virtual machine
Network egress controlWhich hosts the agent can reachAllowlists, proxies, firewall rules
System call filteringWhich kernel operations are allowedseccomp profiles, gVisor
Resource limitsCPU, memory, disk and run timecgroups, quotas, timeouts
Secret handlingExposure of credentials and tokensScoped short-lived tokens, injection proxies
Control layers of an agent sandbox

The sandbox is usually ephemeral: it starts from a known image, lives for one task or session and is destroyed afterward. This fresh-state principle prevents malicious files or altered configuration from persisting between runs.

Isolation technologies and their strength

Agent sandboxes are built on a spectrum of technologies that trade isolation strength against startup time and overhead. The choice depends on whether the agent runs trusted internal code or arbitrary code influenced by outside content.

TechnologyIsolation strengthStartup timeTypical use
Language-level sandboxLowMillisecondsRestricted interpreters, WebAssembly runtimes
OS-level sandboxModerateMillisecondsLocal coding agents on a developer machine
ContainerModerateUnder a second to secondsHosted code execution with shared kernel
User-space kernelHighAbout a secondgVisor-style syscall interception
MicroVMHighRoughly 100 ms to a few secondsMulti-tenant agent platforms such as Firecracker-based services
Full virtual machineVery highTens of secondsComputer-use agents with a desktop
Common isolation technologies for agents

A frequent misconception is that a standard container is a security boundary for hostile code. Containers share the host kernel, so a kernel vulnerability can allow escape; multi-tenant platforms that execute untrusted agent code therefore tend to prefer microVMs or user-space kernels.

An agent sandbox limits what is technically possible, whereas agent permissions and human-in-the-loop review limit what is authorized or approved. These controls complement one another and are not substitutes.

ControlQuestion it answersEnforced by
Agent sandboxWhat can the agent physically reachOperating system or hypervisor
Agent permissionsWhich tools and actions are allowedAgent harness policy
Human-in-the-loopShould this specific action proceedHuman approval step
Agent observabilityWhat did the agent actually doLogs, traces and trajectories
Agent identityOn whose behalf is the agent actingCredentials and access management
Agent safety controls and how they differ

Mature deployments apply defense in depth: the harness asks for approval on risky tools, the sandbox blocks access outside the workspace, and observability records each step so that incidents can be reconstructed.

Designing a sandbox for an agent

A well-designed agent sandbox starts from deny by default and grants only the access a task demonstrably needs. The following practices reflect common engineering guidance for coding and browsing agents.

  1. Mount only the project workspace as writable and keep system directories read-only.
  2. Route outbound traffic through a proxy with a domain allowlist, for example package registries and the source code host.
  3. Provide short-lived, narrowly scoped tokens rather than personal credentials or long-lived API keys.
  4. Set hard limits on run time, memory and disk to stop runaway loops and resource exhaustion.
  5. Snapshot or checkpoint state so that a failed run can be discarded without affecting the host.
  6. Log every command and network request for audit and agent evaluation.

Local sandboxes for developer machines, such as those built on Linux namespaces with seccomp or on macOS sandbox profiles, keep latency low and let the agent work on real files. Hosted platforms instead run each session in a remote microVM, which isolates tenants from one another at the cost of copying the workspace.

Risks a sandbox does not remove

An agent sandbox reduces the blast radius of a compromised agent, but it does not make the agent trustworthy. Several risks remain and must be addressed by other controls.

Residual riskWhy the sandbox misses itMitigation
Data exfiltration through allowed hostsPermitted domains can receive stolen dataNarrow allowlists, content inspection
Damage inside the workspaceThe agent may delete or corrupt project filesVersion control, checkpoints
Misuse of granted tokensValid credentials work as intendedLeast privilege, approval for sensitive calls
Sandbox escapeKernel or hypervisor flaws existPatching, stronger isolation tier
Over-permissive configurationConvenience settings widen accessReviewed policies, periodic audits
Residual risks and mitigations

The most common mistake is granting broad network access for convenience, which turns a contained agent into one that can send secrets anywhere. A second mistake is mounting the home directory, which exposes SSH keys, browser profiles and cloud credentials to the agent.

Put simply

An agent sandbox is a closed workroom for an AI helper. The helper can use tools, write code and run programs inside the room. It cannot wander into the rest of the computer or the network without permission.

Think of a lab with a glove box. Scientists handle risky materials through sealed gloves, so a spill stays inside. The key takeaway is that a sandbox limits the harm of mistakes. It does not make the helper smarter. It simply keeps errors and tricks contained.

In practice

A software team lets a coding agent fix failing tests in a large repository overnight. Each task starts in a fresh microVM containing a copy of the repository, with outbound traffic limited to the internal package mirror and the code hosting service. The agent receives a token that can only open pull requests on that one repository, and every session ends after 60 minutes.

One night, a dependency’s README contains hidden text instructing the agent to upload environment variables to an external server. The agent attempts the request, but the proxy blocks the unknown domain and logs the attempt. The team reviews the trace the next morning, removes the dependency, and the incident causes no credential leak and no damage outside the disposable environment.