Sandbox

In short

A sandbox is an isolated, Unix-like environment in which an AI agent gets a filesystem, a shell, installed packages and controlled access to external systems¹.

Also called: AI sandbox, Sandboxed environment
Topic: AI agents
Level: Beginner

OpenAI’s Agents SDK uses a sandbox when an agent needs to change files, run commands, mount data, produce artefacts, expose a service, or continue work later in the same workspace¹. The SDK splits two roles. The harness owns the agent loop, model calls, tool routing, handoffs, approvals, tracing and run state. The sandbox is where model-directed work reads and writes files, runs commands, installs dependencies and opens ports¹. The docs say the harness can keep authentication, billing, audit logs and human review outside any one container¹. A sandbox agent still has guardrails. What changes is the execution boundary¹.

The SDK can start a temporary workspace on the local machine, or use Docker for local container isolation¹. Docker’s own product for coding agents is a different design. Each sandbox runs in a microVM with its own Linux kernel, so, unlike a container, it does not share the host kernel². Docker describes five isolation layers: the hypervisor, the network, a Docker engine inside the VM, the workspace, and a credential proxy. A host-side proxy injects authentication headers into outbound API requests, and credential values are never stored inside the VM².

OpenAI says entries in the manifest for a fresh workspace cannot use an absolute path or climb out with a parent-directory reference, and that credentials should be injected by the runtime rather than written into the prompt¹. It also says to review artefacts before moving them out, especially if the agent could read private documents¹. Docker’s direct-mount mode shares the working tree as a read-write mount, so there is no file boundary between the agent’s edits and the host². Its clone mode mounts the repository read-only and keeps edits in a private clone, but the mounted tree is still readable, including a file such as .env².

Example

A coding agent is asked to inspect a repository. In OpenAI’s SDK the workspace can fetch that repository so the agent can inspect it inside the sandbox¹. In Docker’s clone mode the host repository is mounted read-only, and the agent edits a private clone inside the VM².

Why it matters

A sandbox is a place for an agent to run commands and change files when a prompt is not enough¹. In Docker’s product, how far those edits reach depends on whether the host directory is mounted read-write, cloned, or left out of the VM².

Questions people ask

Is a sandbox the same as a virtual machine?

Not always. Docker Sandboxes run each agent in a microVM with its own kernel, and Docker contrasts that with containers, which share the host kernel². OpenAI’s SDK can also use a local Unix workspace, or a Docker container, as the place the agent runs¹.

Why do AI agents need a sandbox?

OpenAI says to use one when the answer depends on workspace work, such as files, commands, mounted data, generated files or a preview on an open port, rather than on the prompt alone¹. Docker says coding agents need to execute code, install packages and run tools on a person’s behalf².

Is code in a sandbox completely safe?

No. In Docker’s direct-mount mode the agent can create, change or delete files in the host working tree². Clone mode blocks those writes, but the repository is still mounted read-only, including files such as .env². OpenAI says not to put credentials in the prompt, and to review files before copying them out of the sandbox¹.

Related terms

Tools that use it

Sources

Back to the glossary