Skip to main content
All sandbox endpoints are under /v1/sandboxes. Requests require authentication and are scoped to the caller’s organization.

​
Create sandbox

​
template
string
required
Template name or ID to boot from.
​
mode
string
default:"ephemeral"
ephemeral or persistent.
​
size
string
default:"shared-cpu-1x"
VM preset. See VM sizes.
​
timeout
string
default:"5m"
Duration until auto-destroy (ephemeral only). Examples: 5m, 1h, 30s. Max: 24h.
​
idle_timeout
string
default:"10m"
Duration of inactivity before auto-suspend (persistent only).
​
env
object
Environment variables as key-value pairs.
​
metadata
object
Arbitrary metadata as key-value pairs.
​
egress
object
Outbound firewall policy. If omitted, the template’s default egress policy is used (which itself defaults to allow_all). See Egress controls.
  • mode (string, required) — allow_all or deny_all
  • allow_cidrs (string[]) — CIDRs to allow when mode is deny_all
  • deny_cidrs (string[]) — CIDRs to explicitly block (evaluated before allows)
  • allow_ports (integer[]) — Restrict allow_cidrs to these destination TCP ports
POST /v1/sandboxes

curl -X POST http://localhost:8080/v1/sandboxes \
  -H "Content-Type: application/json" \
  -d '{
    "template": "python",
    "mode": "ephemeral",
    "timeout": "10m",
    "size": "shared-cpu-2x",
    "env": {"API_KEY": "sk-..."}
  }'
StatusCondition
201Sandbox created
400Invalid mode, size, timeout, or egress policy
404Template not found

​
List sandboxes

Returns all non-destroyed sandboxes for the caller’s organization.
​
status
string
Filter by status: creating, running, suspended, destroyed.
GET /v1/sandboxes

curl http://localhost:8080/v1/sandboxes?status=running

​
Get sandbox

GET /v1/sandboxes/{id}

curl http://localhost:8080/v1/sandboxes/sbx_abc123
StatusCondition
200OK
403Sandbox belongs to different organization
404Sandbox not found

​
Destroy sandbox

DELETE /v1/sandboxes/{id}
Returns 204 No Content on success. Idempotent — safe to call multiple times.

​
Keepalive

Extend the expiry of an ephemeral sandbox.
​
timeout
string
New timeout duration from now. Max: 24h.
POST /v1/sandboxes/{id}/keepalive

curl -X POST http://localhost:8080/v1/sandboxes/sbx_abc123/keepalive \
  -H "Content-Type: application/json" \
  -d '{"timeout": "30m"}'
StatusCondition
200Timeout extended
409Not ephemeral, or not running

​
Wake sandbox

Wake a suspended persistent sandbox. 
POST /v1/sandboxes/{id}/wake

curl -X POST http://localhost:8080/v1/sandboxes/sbx_def456/wake
StatusCondition
200Sandbox woken (or was already running)
409Sandbox is in a state that cannot be woken

​
Execute command

Run a command inside a running sandbox.
​
command
string
required
The shell command to execute.
​
timeout
string
default:"30s"
Execution timeout. Max: 5m.
​
workdir
string
Working directory for the command.
​
env
object
Additional environment variables for this execution.
POST /v1/sandboxes/{id}/execute

curl -X POST http://localhost:8080/v1/sandboxes/sbx_abc123/execute \
  -H "Content-Type: application/json" \
  -d '{
    "command": "python3 -c \"import os; print(os.cpu_count())\"",
    "timeout": "10s"
  }'
StatusCondition
200Command completed (check exit_code for success/failure)
400Missing command or invalid timeout
409Sandbox not running

​
Upload file

Write a file to the sandbox filesystem. 
PUT /v1/sandboxes/{id}/files/{path}
Send the file contents as the request body. Parent directories are created automatically. 
curl -X PUT http://localhost:8080/v1/sandboxes/sbx_abc123/files/home/user/main.py \
  --data-binary @./main.py
StatusCondition
204File uploaded
400Invalid path (root, contains ..) or exceeds 100 MB
409Sandbox not running

​
Download file

Read a file from the sandbox filesystem. 
GET /v1/sandboxes/{id}/files/{path}
Returns the raw file contents with Content-Type: application/octet-stream. 
curl http://localhost:8080/v1/sandboxes/sbx_abc123/files/home/user/output.json -o output.json
StatusCondition
200File contents
404File not found
409Sandbox not running

​
List directory

List the contents of a directory in the sandbox. 
GET /v1/sandboxes/{id}/files/{path}?list=true

curl "http://localhost:8080/v1/sandboxes/sbx_abc123/files/home/user?list=true"

​
Warm pool status

Admin-only endpoint showing the current warm pool state. 
GET /v1/sandboxes/pool

{
  "enabled": true,
  "templates": [
    {"template_name": "python", "ready_count": 3, "claimed_count": 0, "target": 3},
    {"template_name": "node", "ready_count": 2, "claimed_count": 0, "target": 2}
  ]
}