Sandboxes

Create Sandbox

string

required

Base image template. See Available Templates below.

integer

Number of vCPUs (1-8, default: 2).

integer

Memory in MB (128-8192, default: 512).

integer

Disk in GB (1-50, default: 5).

string

Network access: full, none, or allowlist.

string[]

Allowed hosts when network_mode is allowlist.

object

Environment variables as key-value pairs.

string

Git repository URL to clone (HTTPS).

string

PAT or OAuth token for private repositories. GitHub: ghp_..., GitLab: personal access token.

string

Branch to checkout (default: main/master).

string

Specific commit SHA to checkout (overrides repo_branch).

string

Monorepo subdirectory to extract into /workspace.

number

Maximum spend in USD.

string

Shell command to run after creation.

integer

Idle timeout in seconds before auto-sleep.

string[]

Packages to pre-install (npm/pip packages).

string[]

AI agents to install: claude, aider, codex.

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"
  }'

Private Repository Example

curl -X POST https://api.caged.dev/v1/sandboxes \
  -H "Authorization: Bearer caged_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template": "node-20",
    "repo": "https://github.com/your-org/private-repo",
    "repo_token": "ghp_xxxxxxxxxxxx",
    "repo_branch": "develop",
    "agents": ["claude"],
    "budget": 10.00
  }'

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_..."

Execute a Command

Run a shell command inside a sandbox and get the output back. Supports pipes, redirects, and environment variables. This is how you interact with sandboxes programmatically — including prompting installed AI agents. POST /v1/sandboxes/{id}/exec

string

required

Shell command to execute. Runs via /bin/sh -c inside the sandbox with the sandbox’s environment (including any env vars set at creation).

curl -X POST https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/exec \
  -H "Authorization: Bearer caged_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"command": "python --version"}'

Response 200 OK

{
  "output": "Python 3.12.3\n",
  "exit_code": 0
}

Prompting an agent — if the sandbox was created with "agents": ["claude"], you can prompt Claude Code non-interactively:

curl -X POST https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/exec \
  -H "Authorization: Bearer caged_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"command": "cd /workspace && claude -p \"Summarize what this repo does\""}'

Error semantics — the three outcomes are distinguishable:

Case	`exit_code`	`error`	Meaning
Success	`0`	empty	Command ran and succeeded
Command failed	non-zero	empty	Command ran; its stderr is in `output`
Infrastructure failure	`1`	set	Sandbox unreachable, not running, etc.

A failed command still returns HTTP 200 — the API call succeeded; the command result is data. Exec requests can run for up to 5 minutes, so long agent prompts are fine.

For a fully interactive TTY session (e.g. the Claude Code TUI), use the terminal WebSocket instead: wss://api.caged.dev/v1/sandboxes/{id}/terminal.

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

Available Templates

Pre-configured sandbox environments with common runtimes and tools.

JavaScript / TypeScript

Template	Runtime	Includes
`node-22`	Node.js 22.x LTS	npm, yarn, pnpm, typescript
`node-20`	Node.js 20.x LTS	npm, yarn, pnpm, typescript

Python

Template	Runtime	Includes
`python-312`	Python 3.12	pip, poetry, virtualenv, black, ruff
`python-311`	Python 3.11	pip, poetry, virtualenv, black, ruff

Base

Template	Description
`minimal`	Ubuntu 24.04 with SSH, git, curl, build-essential. Install any runtime yourself.

Using minimal? You can install any runtime manually. The sandbox persists your changes until destroyed.

​Sandboxes

​Create Sandbox

​List Sandboxes

​Get Sandbox

​Execute a Command

​Pause Sandbox

​Resume Sandbox

​Destroy Sandbox

​Available Templates

​JavaScript / TypeScript

​Python

​Base

Sandboxes

Create Sandbox

List Sandboxes

Get Sandbox

Execute a Command

Pause Sandbox

Resume Sandbox

Destroy Sandbox

Available Templates

JavaScript / TypeScript

Python

Base