Skip to main content

​
Sandboxes

​
Create Sandbox

​
template
string
required
Base image. Options: node-20, python-312, go-122, minimal.
​
cpus
integer
Number of vCPUs (1-8, default: 2).
​
memory_mb
integer
Memory in MB (128-8192, default: 512).
​
disk_gb
integer
Disk in GB (1-50, default: 5).
​
network_mode
string
Network access: full, none, or allowlist.
​
allowlist
string[]
Allowed hosts when network_mode is allowlist.
​
env
object
Environment variables as key-value pairs.
​
repo
string
Git repository URL to clone.
​
budget
number
Maximum spend in USD.
​
init_script
string
Shell command to run after creation.
​
timeout
integer
Idle timeout in seconds before auto-sleep.
curl -X POST https://api.caged.dev/v1/sandboxes \
  -H "Authorization: Bearer caged_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template": "node-20",
    "cpus": 2,
    "memory_mb": 1024,
    "repo": "https://github.com/user/project",
    "budget": 5.00,
    "init_script": "npm install"
  }'
Response 201 Created 
{
  "id": "cage-a1b2c3d4",
  "status": "running",
  "template": "node-20",
  "ip": "10.0.1.42",
  "cpus": 2,
  "memory_mb": 1024,
  "disk_gb": 5,
  "network_mode": "full",
  "created_at": "2026-06-08T10:00:00Z"
}

​
List Sandboxes

curl https://api.caged.dev/v1/sandboxes \
  -H "Authorization: Bearer caged_sk_..."
Response 200 OK 
[
  {
    "id": "cage-a1b2c3d4",
    "status": "running",
    "template": "node-20",
    "cpus": 2,
    "memory_mb": 1024,
    "created_at": "2026-06-08T10:00:00Z"
  }
]

​
Get Sandbox

curl https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4 \
  -H "Authorization: Bearer caged_sk_..."

​
Pause Sandbox

Freezes the sandbox in memory. No compute charges while paused. An auto-snapshot is created. 
curl -X POST https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/pause \
  -H "Authorization: Bearer caged_sk_..."

​
Resume Sandbox

Unfreezes a paused sandbox. 
curl -X POST https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/resume \
  -H "Authorization: Bearer caged_sk_..."

​
Destroy Sandbox

Permanently destroys a sandbox and all its data.
This action is irreversible. Create a snapshot first if you need to preserve the state.
curl -X DELETE https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4 \
  -H "Authorization: Bearer caged_sk_..."
Response 204 No Content