Sandbox Execution

Sandboxes provide multiple ways to execute code and commands, from one-off shell commands to interactive terminal sessions.

Shell Commands

The /v1/sandboxes/exec endpoint runs a shell command and returns the result:

curl -X POST "https://api.boxes.banata.dev/v1/sandboxes/exec" \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "SANDBOX_ID",
    "command": "echo hello && date"
  }'

The response is proxied directly from the sandbox worker and includes the command output.

Request fields

Requirements

The sandbox must be in ready or active state. If the sandbox is still starting up (queued or assigning), the API returns 409 Sandbox is not ready.

Long-running commands

Commands that take time (installing packages, building projects) work the same way — the response is returned when the command finishes. Set the timeout field or an appropriate timeout on your HTTP client.

curl -X POST "https://api.boxes.banata.dev/v1/sandboxes/exec" \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "SANDBOX_ID",
    "command": "cd /workspace && bun install && bun run build",
    "timeout": 60000
  }'

Code Snippets

The /v1/sandboxes/code endpoint executes code directly without needing to write a file first:

curl -X POST "https://api.boxes.banata.dev/v1/sandboxes/code" \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "SANDBOX_ID",
    "code": "const response = await fetch(\"https://api.example.com/data\"); console.log(await response.json());"
  }'

Request fields

The code is executed using the sandbox's runtime:

Code snippets have access to the full sandbox environment, including installed packages and files in /workspace.

Interactive Terminal

For interactive use, get a WebSocket URL and authentication token for a live terminal session:

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

Response:

{
  "terminalUrl": "wss://...",
  "token": "eyJ..."
}

Connect to terminalUrl with a WebSocket client to get a fully interactive shell. This supports:

• Command history and tab completion
• Interactive programs (vim, top, htop)
• Long-running processes
• Multiple concurrent terminal connections to the same sandbox

The terminal connection is authenticated with the token value.

Working Directory

Every sandbox starts with /workspace as the default working directory. This is where your project files live and where commands execute by default.

The /workspace directory persists for the full sandbox lifecycle:

• During active use — Files are available immediately as you create them.
• Across pause/resume — Workspace survives suspension and resumption.
• After ending — Workspace is destroyed unless you create a checkpoint first.

Common Patterns

Install dependencies and run a build

{
  "id": "SANDBOX_ID",
  "command": "cd /workspace && bun install && bun run build"
}

Run a Python script

{
  "id": "SANDBOX_ID",
  "code": "import json\ndata = {'hello': 'world'}\nprint(json.dumps(data, indent=2))"
}

Clone a repository and set up

{
  "id": "SANDBOX_ID",
  "command": "cd /workspace && git clone https://github.com/user/repo.git && cd repo && bun install"
}

Error Responses

Next Steps

• Sandbox File System — File operations, uploads, and downloads
• Sandbox Capabilities — Browser pairing, AI agents, and human handoff
• Sandboxes — Overview and session management