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

​
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.