Sandboxes API

Manage sandboxes through the REST API: create isolated workspaces, list active sandboxes, pause and resume state, and terminate when done.

Endpoints

---

POST /v1/sandboxes

Create a new sandbox.

Request

curl -X POST https://api.box.runra.dev/v1/sandboxes \
  -H "Authorization: Bearer $RUNRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "node:22",
    "resources": {
      "cpu": 2,
      "memoryMb": 4096,
      "diskMb": 10240
    },
    "env": {
      "NODE_ENV": "production",
      "CI": "true"
    },
    "workdir": "/workspace",
    "timeoutMs": 300000,
    "idleTimeoutMs": 120000,
    "metadata": {
      "userId": "user_123",
      "projectId": "proj_456"
    },
    "network": {
      "egress": {
        "allow": ["github.com", "registry.npmjs.org"],
        "default": "deny"
      }
    }
  }'

Request Body

Field	Type	Required	Default	Description
image	string	Yes	—	Base image: node:22, python:3.12, ubuntu:24.04, custom
resources.cpu	integer	No	2	vCPUs: 2, 4, or 8
resources.memoryMb	integer	No	4096	Memory in MB: 2048–16384
resources.diskMb	integer	No	10240	Disk in MB: 5120–51200
env	object	No	{}	Environment variables injected at start
workdir	string	No	/workspace	Default working directory
timeoutMs	integer	No	300000	Max sandbox lifetime in ms (max 86400000 = 24h)
idleTimeoutMs	integer	No	120000	Auto-pause after idle in ms
metadata	object	No	{}	Custom key-value tags (max 20 keys, values ≤ 256 chars)
network.egress.allow	string[]	No	Allow all	Domains to allow egress to
network.egress.default	string	No	"allow"	Default egress policy: "allow" or "deny"

Response — 201 Created

{
  "id": "sb_x7k2m9p4q1w3v5b8n",
  "state": "running",
  "image": "node:22",
  "resources": {
    "cpu": 2,
    "memoryMb": 4096,
    "diskMb": 10240
  },
  "env": {
    "NODE_ENV": "production",
    "CI": "true"
  },
  "workdir": "/workspace",
  "timeoutMs": 300000,
  "idleTimeoutMs": 120000,
  "metadata": {
    "userId": "user_123",
    "projectId": "proj_456"
  },
  "network": {
    "egress": {
      "allow": ["github.com", "registry.npmjs.org"],
      "default": "deny"
    }
  },
  "createdAt": "2026-06-15T10:30:00.000Z",
  "startedAt": "2026-06-15T10:30:05.000Z"
}

Quickest Create

Minimal sandbox creation with sensible defaults:

curl -X POST https://api.box.runra.dev/v1/sandboxes \
  -H "Authorization: Bearer $RUNRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "node:22"}'

---

GET /v1/sandboxes

List all sandboxes with optional filters.

Request

curl "https://api.box.runra.dev/v1/sandboxes?state=running&limit=10&offset=0" \
  -H "Authorization: Bearer $RUNRA_API_KEY"

Query Parameters

Parameter	Type	Default	Description
state	string	—	Filter by state: running, paused, terminated
image	string	—	Filter by image name
limit	integer	20	Items per page (max 100)
offset	integer	0	Items to skip
metadata.userId	string	—	Filter by metadata key (any metadata.* key works)

Response — 200 OK

{
  "data": [
    {
      "id": "sb_x7k2m9p4q1w3v5b8n",
      "state": "running",
      "image": "node:22",
      "resources": { "cpu": 2, "memoryMb": 4096, "diskMb": 10240 },
      "createdAt": "2026-06-15T10:30:00Z",
      "startedAt": "2026-06-15T10:30:05Z"
    },
    {
      "id": "sb_a1b2c3d4e5f6g7h8i",
      "state": "paused",
      "image": "python:3.12",
      "resources": { "cpu": 2, "memoryMb": 4096, "diskMb": 10240 },
      "createdAt": "2026-06-15T09:45:00Z",
      "pausedAt": "2026-06-15T10:15:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

---

GET /v1/sandboxes/:id

Retrieve a single sandbox by its ID.

Request

curl https://api.box.runra.dev/v1/sandboxes/sb_x7k2m9p4q1w3v5b8n \
  -H "Authorization: Bearer $RUNRA_API_KEY"

Response — 200 OK

Same shape as the create response.

Error — 404 Not Found

{
  "error": {
    "code": "SANDBOX_NOT_FOUND",
    "message": "Sandbox sb_x7k2m9p4q1w3v5b8n not found",
    "details": { "sandboxId": "sb_x7k2m9p4q1w3v5b8n" },
    "requestId": "req_a1b2c3d4"
  }
}

---

POST /v1/sandboxes/:id/pause

Pause a running sandbox, preserving its filesystem and process state. The sandbox stops consuming compute resources but retains its disk.

Request

curl -X POST https://api.box.runra.dev/v1/sandboxes/sb_x7k2m9p4q1w3v5b8n/pause \
  -H "Authorization: Bearer $RUNRA_API_KEY"

Response — 200 OK

{
  "id": "sb_x7k2m9p4q1w3v5b8n",
  "state": "paused",
  "pausedAt": "2026-06-15T11:00:00.000Z",
  "runtimeDurationMs": 1800000
}

Constraints

• Can only pause sandboxes in running state.
• Pausing is near-instantaneous (typically < 2s).
• Paused sandboxes auto-resume on the next execute request.

---

POST /v1/sandboxes/:id/resume

Resume a paused sandbox. The sandbox restores its full filesystem and becomes ready for execution.

Request

curl -X POST https://api.box.runra.dev/v1/sandboxes/sb_x7k2m9p4q1w3v5b8n/resume \
  -H "Authorization: Bearer $RUNRA_API_KEY"

Response — 200 OK

{
  "id": "sb_x7k2m9p4q1w3v5b8n",
  "state": "running",
  "resumedAt": "2026-06-15T11:30:00.000Z",
  "pausedDurationMs": 1800000
}

Constraints

• Can only resume sandboxes in paused state.
• Resume typically takes 3–10 seconds.
• Environment variables, filesystem, and running processes are restored.
• The sandbox's original timeoutMs and idleTimeoutMs remain in effect.

---

DELETE /v1/sandboxes/:id

Permanently terminate and destroy a sandbox. All filesystem data is irrevocably deleted.

Request

curl -X DELETE https://api.box.runra.dev/v1/sandboxes/sb_x7k2m9p4q1w3v5b8n \
  -H "Authorization: Bearer $RUNRA_API_KEY"

Response — 200 OK

{
  "id": "sb_x7k2m9p4q1w3v5b8n",
  "state": "terminated",
  "terminatedAt": "2026-06-15T12:00:00.000Z",
  "totalRuntimeMs": 5400000
}

Constraints

• Can terminate sandboxes in any state (running, paused, creating).
• Termination is irreversible.
• Cannot execute or resume a terminated sandbox.

---

State Transitions

POST /sandboxes          →  creating → running
POST /sandboxes/:id/pause  →  running  → paused
POST /sandboxes/:id/resume →  paused   → running
DELETE /sandboxes/:id      →  any      → terminated

Common Errors

Status	Code	Scenario
400	INVALID_CONFIG	cpu value not in [2, 4, 8]
409	INVALID_STATE	Pausing an already-paused sandbox
429	RATE_LIMITED	Exceeded sandbox creation rate limit
503	RESOURCE_EXHAUSTED	No compute capacity available

Next Steps

• Execution API — run code inside sandboxes
• SDK Reference — TypeScript SDK methods
• Concepts: Sandboxes — lifecycle and isolation