Sandboxes

A sandbox is an isolated Linux environment running on a dedicated machine. You get a full shell, file system access, and the ability to run code in multiple runtimes. Sandboxes are designed for tasks that go beyond browser automation — code generation, data processing, build pipelines, and multi-step AI agent workflows.

Creating a Sandbox

curl -X POST "https://api.boxes.banata.dev/v1/sandboxes" \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "runtime": "bun"
  }'

Response:

{
  "id": "k82g51hl3on646lel50o9f162t92xu7z",
  "status": "queued",
  "runtime": "bun",
  "size": "standard",
  "capabilities": null
}

Poll GET /v1/sandboxes?id=... until the status becomes ready.

An empty body {} creates a sandbox with defaults: bun runtime, the standard sandbox compute shape, and ephemeral storage.

Runtimes

You can install additional packages within a running sandbox using the runtime's package manager (bun add, pip install, apt-get).

Compute Shape

All sandboxes currently run on the same standard machine shape for stability:

The public API and SDK expose a single sandbox size value: standard.

Session Options

env

Type: Record<string, string> (optional)

Environment variables to set in the sandbox:

{
  "runtime": "bun",
  "env": {
    "API_KEY": "sk_test_...",
    "NODE_ENV": "production"
  }
}

ephemeral

Type: boolean Default: true

Whether the sandbox workspace is ephemeral. When true, the workspace is destroyed when the session ends. Set to false to enable checkpointing.

maxDurationMs

Type: number (optional) Default: Your plan's maximum sandbox duration

Maximum session duration in milliseconds. Must be positive and cannot exceed your plan's limit:

region

Type: string (optional)

A 3-letter region code (e.g., iad, lhr) for preferred machine placement. Must match /^[a-z]{3}$/.

capabilities

Type: object (optional)

Enable advanced features. See Sandbox Capabilities for full details.

{
  "runtime": "bun",
  "capabilities": {
    "opencode": { "enabled": true, "defaultAgent": "build", "allowPromptApi": true },
    "browser": { "mode": "paired-banata-browser", "recording": true, "streamPreview": true },
    "documents": { "libreofficeHeadless": true },
    "storage": { "workspace": "checkpointed", "artifactPrefix": "my-project/" }
  }
}

Reading Sandbox Status

Single sandbox

curl "https://api.boxes.banata.dev/v1/sandboxes?id=SANDBOX_ID" \
  -H "Authorization: Bearer br_live_..."

Response:

{
  "id": "k82g51hl3on646lel50o9f162t92xu7z",
  "status": "ready",
  "runtime": "bun",
  "size": "standard",
  "region": "iad",
  "terminalUrl": "wss://...",
  "previewBaseUrl": null,
  "capabilities": null,
  "pairedBrowser": null,
  "opencode": null,
  "browserPreview": null,
  "humanHandoff": null,
  "artifacts": null,
  "duration": null,
  "createdAt": 1772078705353
}

List all sandboxes

Omit the id to list all sandbox sessions for your organization:

curl "https://api.boxes.banata.dev/v1/sandboxes" \
  -H "Authorization: Bearer br_live_..."

Response:

{
  "items": [
    {
      "id": "k82g51hl3on646lel50o9f162t92xu7z",
      "status": "ready",
      "runtime": "bun",
      "size": "standard",
      "region": "iad",
      "createdAt": 1772078705353,
      "startedAt": 1772078708000
    }
  ]
}

Sandbox States

Pause and Resume

Sandboxes support pausing to save costs during idle periods. A paused sandbox preserves workspace state and can be resumed later.

Pause

curl -X POST "https://api.boxes.banata.dev/v1/sandboxes/pause" \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{"id": "SANDBOX_ID"}'

Resume

curl -X POST "https://api.boxes.banata.dev/v1/sandboxes/resume" \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{"id": "SANDBOX_ID"}'

After resuming, the sandbox re-enters the queued → assigning → ready flow. Your workspace files and state are preserved.

Ending a Sandbox

curl -X DELETE "https://api.boxes.banata.dev/v1/sandboxes?id=SANDBOX_ID" \
  -H "Authorization: Bearer br_live_..."

Response: { "ok": true }

This stops the machine and cleans up resources. If you need to preserve workspace contents, create a checkpoint or download artifacts before ending the session.

Concurrent Sandbox Limits

Monthly Sandbox Hours

Error Responses

Next Steps

• Sandbox Execution — Running commands and code
• Sandbox File System — File operations, checkpoints, and artifacts
• Sandbox Capabilities — Browser pairing, AI agents, and human handoff
• API Reference — Full endpoint documentation