Agents and control
Sandboxes
Give an agent a throwaway machine to run code in, watch its commands live, and take over when you need to.
A sandbox is a throwaway, sealed-off computer for running code without deploying anything: testing a snippet, converting a file, trying a package. Agents use them most, and you can watch every command they run as it happens, or take over yourself.
How to do it: ask your agent to use one, or make one in project settings under Sandboxes.
"Try this script in a sandbox and show me the output."
Sandboxes are billed by the minute and removed when they're done.
A sandbox is a throwaway, isolated machine for running code without deploying anything: testing a snippet, transforming a file, trying a package. Agents use them most, and you can watch every command they run as it prints, or take the wheel yourself.
Create a sandbox
Ask your agent:
"Start a Python sandbox, load sales.csv and tell me which month had the most orders. Delete the sandbox when you're done."
With the API:
POST /v1/projects/:id/sandboxes{ "image": "python", "cpu": 1, "memMb": 1024, "network": false }The MCP tool is cli_sandbox_create. Creating one needs the deploy scope, and the key's spending limits apply.
Images
Use a preset or any image reference:
| Preset | Image |
|---|---|
python (default) | python:3.12-slim |
node | node:22-slim |
ubuntu | ubuntu:24.04 |
go | golang:1.23 |
rust | rust:1.82-slim |
Size
A sandbox takes 0.25 to 4 vCPUs and 256 to 8192 MB of memory. It starts with 1 vCPU and 1024 MB if you don't say. A project can run up to 10 sandboxes at once.
Network
Sandboxes have no network unless you ask for it with "network": true. When you do, the sandbox gets internet through a network of its own, which can't reach your apps or other sandboxes.
Sandboxes run under gVisor, the same isolation as apps. /work is a RAM disk, counted against the sandbox's memory.
Run commands
Each command runs with sh -c in /work, and you get back the exit code, stdout, stderr and whether it timed out.
POST /v1/sandboxes/:id/exec{ "command": "pip install pandas && python clean.py", "timeoutSeconds": 300 }Commands time out after 60 seconds unless you give timeoutSeconds (up to 900). Only the last 1 MB of each output comes back. The MCP tool is cli_sandbox_exec.
Move files in and out
Write a file as text, or as base64 for bytes:
PUT /v1/sandboxes/:id/files{ "path": "/work/sales.csv", "content": "month,orders\n2026-09,412\n2026-10,388\n" }Read one back with GET /v1/sandboxes/:id/files?path=/work/report.json. Text comes back as text, anything else as base64. Files are up to 10 MB each. The MCP tools are cli_sandbox_write_file and cli_sandbox_read_file.
Limits and billing
- Start: 0.001 USDC per sandbox.
- Running: billed per second for its CPU and memory, at the same rates as apps, from the moment it starts until it's deleted.
- Idle: deleted after 10 minutes without a command. A long-running command counts as busy, not idle.
- Maximum: deleted after 1 hour, whatever is happening.
You can shorten either limit with idleMinutes and maxMinutes when you create it (1 to 60 minutes). A sandbox is also stopped if the project runs out of credit or is suspended.
Delete a sandbox as soon as you're done:
DELETE /v1/sandboxes/:idBilling stops at that moment. The MCP tool is cli_sandbox_delete. What sandboxes cost shows up under Sandboxes in the project's money flow (see /docs/billing).
The shared terminal
Every command run in a sandbox, by an agent or a person, goes into one shared transcript in order, with who ran it, its status, its exit code and its output.
Watch an agent work
- Open the project, go to Settings, then Sandboxes.
- Press Watch on the sandbox. Its page opens as a terminal.
- Each command appears as the agent runs it, labelled agent or with the person's name. Output streams in line by line while the command runs, then the exit code shows when it finishes.
The page header shows the image, size, whether internet is on, when it will be deleted at the latest, and what it has cost so far.
Follow the output with the API
The transcript lists every command after a sequence number:
GET /v1/sandboxes/:id/runs?after=12For a command that's still running, read what it has printed so far. Pass back the offsets from the last answer to get only what's new:
GET /v1/sandboxes/:id/runs/run_8e2f41c0a7b93d56e1f0/output?out=2048&err=0Or stream it as server-sent events: one output event for each new piece of output, then an end event with the exit code. Send your token in the Authorization header.
GET /v1/sandboxes/:id/runs/run_8e2f41c0a7b93d56e1f0/stream{ "status": "done", "exitCode": 0, "timedOut": false }Reading the transcript and live output needs the developer role or higher.
Take the wheel
When you want to step in, take over the sandbox:
- On the sandbox's page, press Take the wheel.
- Type commands yourself in the terminal. While you hold it, anyone else's commands, including the agent's, are refused with
CONFLICT. - When you're done, press Hand it back. The agent can run commands again.
Agents are told to stop and wait when they get CONFLICT from a sandbox, and to read the transcript to see what you did before carrying on.
With the API:
POST /v1/sandboxes/:id/hold{ "hold": true }Send { "hold": false } to hand it back. Only a signed-in person can take the wheel, never a key, and only one person can hold it at a time.