Skip to main content
The Sandbox gives an agent a secure, isolated environment — a gVisor micro-VM — where it can run shell commands, execute code, install packages, and read and write files. Unlike one-shot Code Execution, the sandbox persists across the conversation, so the agent can work step by step: fetch data, transform it, and produce a finished artifact.

​
Why it’s safe

Isolated

Each sandbox is a gVisor micro-VM with its own filesystem — code runs isolated from the platform and from other workspaces.

Network-jailed

Private/internal network ranges are blocked; the sandbox can’t reach internal services.

Ephemeral

Sandboxes are torn down when idle, so nothing lingers after the task is done.

Permission-gated

Running code requires the sandboxes:run permission — it’s never implied by general access and must be granted explicitly.

​
What agents use it for

  • Multi-step data processing that needs a real filesystem
  • Building a report, spreadsheet, or document over several turns
  • Running scripts or tooling and returning the output as a file

​
What the agent can do

The sandbox gives the agent a small, careful set of tools:
  • Read and edit files safely. A read tags every line with a short content hash, and an edit names the lines it means by those hashes. An edit written against content that has since changed is refused instead of overwriting it.
  • Search and list. Find files by name pattern or search their contents by regular expression, both capped so a large tree can’t flood the conversation.
  • Run commands, in the foreground or the background. A foreground command returns its output; a long-running one (a server, a watcher) is started in the background, then followed or stopped by id.
  • Protected paths. .env files, private keys and secrets can be read but never written, at any path.
Every agent gets this set. An agent deliberately pinned to the previous sandbox version keeps the tools it was built with.

​
Approvals

The sandbox executes real code, so you can gate it: require your approval before the agent runs commands or writes files. This keeps a human in the loop for higher-stakes automation while still letting the agent propose the work. Enable the sandbox per agent under Agent Tools.

​
Programmatic sandboxes

The same sandbox capability is available directly — create a sandbox, run commands, and read/write files from code — without an agent:

Sandboxes in the SDK

client.sandboxes.create(), sandbox.commands.run(...), sandbox.files.write/read(...).

Sandboxes API

The REST endpoints under /v1/sandboxes.