Sandbox API

Scalebox Regions (Discovery)

Call GET /v1/scalebox-regions to obtain id / name pairs for regions that currently have eligible capacity. Those ids are what you pass in locality.region when creating a sandbox. The same ids are validated against the global locality catalog; unknown regions return 400.

Sandbox Statuses

The sandbox status indicates its current lifecycle state:

Response Conventions

Most JSON endpoints on this page return the standard envelope:

{
  "success": true,
  "data": {},
  "timestamp": "2026-04-17T12:34:56Z"
}

Special cases:

• GET /v1/scalebox-regions is public, but still uses the JSON envelope.
• POST /v1/sandboxes/{sandbox_id}/exec, GET /v1/sandboxes/{sandbox_id}/exec/active, and DELETE /v1/sandboxes/{sandbox_id}/exec return raw JSON without the standard envelope.
• GET /v1/sandboxes/{sandbox_id}/exec/stream returns text/event-stream (SSE), not JSON.

Read Sandbox Object

GET /v1/sandboxes/{sandbox_id} and successful pause/resume responses return a rich sandbox object. The backend currently exposes:

• Identity and ownership: sandbox_id, name, description, status, substatus, reason, template_id, template_name, template_exists, project_id, project_name, owner, account_owner, and legacy compatibility fields user_account_id, userName, userEmail, region, visibility
• Resources and access: cpu_count, memory_mb, storage_gb, resources, timeout, auto_pause, secure, allow_internet_access, sandbox_domain, sandbox_domain_internal, web_terminal_available, web_files_available, envd_access_token
• Configuration and mounts: metadata, env_vars, object_storage, object_storage_single, object_storage_direct_mount, object_storage_s3fs_path, ports, template_ports, custom_ports, template_custom_command, template_ready_command, template_source
• Lifecycle and timing: created_at, updated_at, started_at, stopped_at, ended_at, timeout_at, remaining_seconds, paused_at, pausing_at, resumed_at, uptime, total_paused_seconds, total_running_seconds, actual_total_paused_seconds, actual_total_running_seconds, lifecycle_outcome, last_accessed_at
• Persistence and optional helpers: persistence_days, persistence_expires_at, persistence_days_remaining, optional network_proxy, and optional webrtc_turn

API Endpoints

Create Sandbox

POST /v1/sandboxes

Create a new sandbox. Default (sync): wait until running or failed. Set is_async: true to return immediately and poll status.

Request Parameters

Success response

201 Created in the standard envelope. data includes:

• sandbox_id, name, description, template_id, owner_user_id, project_id
• cpu_count, memory_mb, storage_gb, timeout, auto_pause, secure, allow_internet_access
• metadata, env_vars
• object_storage, object_storage_single, object_storage_direct_mount, object_storage_s3fs_path
• ports, template_ports, custom_ports
• template_custom_command, template_ready_command
• status, substatus, reason, created_at
• sandbox_domain, sandbox_domain_internal, web_terminal_available, web_files_available, envd_access_token
• persistence_days, persistence_expires_at, persistence_days_remaining
• optional network_proxy

Default sync mode waits for the sandbox to reach running or failed. Async mode returns the same shape earlier, typically with status: "created" or status: "starting".

Example

curl -X POST https://api.scalebox.dev/v1/sandboxes \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-dev",
    "template": "python-dev",
    "cpu_count": 2,
    "memory_mb": 4096,
    "storage_gb": 10,
    "timeout": 3600,
    "auto_pause": true,
    "is_async": false,
    "env_vars": {
      "DEBUG": "true",
      "API_KEY": "your-secret-key"
    },
    "metadata": {
      "project": "web-app",
      "environment": "development"
    },
    "object_storage": {
      "uri": "s3://my-bucket/data",
      "mount_point": "/mnt/oss",
      "access_key": "YOUR_S3_ACCESS_KEY",
      "secret_key": "YOUR_S3_SECRET_KEY",
      "region": "us-east-1"
    },
    "custom_ports": [
      { "port": 8080, "name": "web-server", "protocol": "tcp" },
      { "port": 9000, "name": "api-server", "protocol": "tcp" }
    ],
    "locality": {
      "region": "ap-southeast",
      "force": false
    }
  }'

List Scalebox Regions

GET /v1/scalebox-regions

Public discovery: Scalebox region ids that currently have at least one eligible cluster.

Success response

200 OK in the standard envelope with data.scalebox_regions, an array of { id, name } objects. The array may be empty when no region currently has eligible cluster capacity.

Example

curl -X GET https://api.scalebox.dev/v1/scalebox-regions

List Sandboxes

GET /v1/sandboxes

List all sandboxes for the authenticated user.

Success response

200 OK in the standard envelope with:

• data.sandboxes: array of sandbox summary objects. Each item includes sandbox_id, name, description, template_id, template_name, template_exists, owner_user_id, project_id, project_name, cpu_count, memory_mb, storage_gb, timeout, timeout_at, remaining_seconds, auto_pause, secure, allow_internet_access, metadata, env_vars, object_storage, object_storage_single, object_storage_direct_mount, object_storage_s3fs_path, ports, template_ports, custom_ports, template_custom_command, template_ready_command, template_source, status, substatus, reason, started_at, stopped_at, created_at, updated_at, sandbox_domain, sandbox_domain_internal, web_terminal_available, web_files_available, paused_at, pausing_at, resumed_at, total_paused_seconds, lifecycle_outcome, persistence_days, persistence_expires_at, persistence_days_remaining, uptime, and optional network_proxy. Root/admin-style owner metadata may also be present when exposed by the backend.
• data.pagination: object with page, limit, total, total_pages, and optional offset

Example

curl -X GET https://api.scalebox.dev/v1/sandboxes \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"

Get Sandbox

GET /v1/sandboxes/{sandbox_id}

Get detailed information about a specific sandbox.

Success response

200 OK in the standard envelope with data set to one Read Sandbox Object.

Example

curl -X GET https://api.scalebox.dev/v1/sandboxes/sbx-abc123def456789 \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"

Update Sandbox

PUT /v1/sandboxes/{sandbox_id}

Update sandbox configuration (extend timeout only).

Request Parameters

Success response

200 OK with top-level message: "Sandbox updated successfully". No data object is returned.

Example

curl -X PUT https://api.scalebox.dev/v1/sandboxes/sbx-abc123def456789 \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{"timeout": 7200}'

Delete Sandbox

DELETE /v1/sandboxes/{sandbox_id}

Delete a sandbox and all associated resources.

Success response

202 Accepted with top-level message: "Sandbox deletion initiated" and:

• data.sandbox_id
• data.status - deletion_in_progress
• data.note

Example

curl -X DELETE https://api.scalebox.dev/v1/sandboxes/sbx-abc123def456789 \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"

Pause Sandbox

POST /v1/sandboxes/{sandbox_id}/pause

Pause a running sandbox. Default (sync): wait until paused or rollback to running.

Request Parameters

Success response

200 OK in the standard envelope.

• Sync mode waits and returns data as the updated Read Sandbox Object (typically status: "paused").
• Async mode returns the current Read Sandbox Object immediately after the transition starts (typically status: "pausing").

Example

curl -X POST https://api.scalebox.dev/v1/sandboxes/sbx-abc123def456789/pause \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{"is_async": false}'

Resume Sandbox

POST /v1/sandboxes/{sandbox_id}/resume

Resume a paused sandbox. Default (sync): wait until running or rollback to paused.

Request Parameters

Success response

200 OK in the standard envelope.

• Sync mode waits and returns data as the updated Read Sandbox Object (typically status: "running").
• Async mode returns a smaller data object with sandbox_id, status: "resuming", and message: "Resume operation initiated".

Example

curl -X POST https://api.scalebox.dev/v1/sandboxes/sbx-abc123def456789/resume \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{"is_async": false}'

Example (OSS delta on resume — delete one mount by mount_point):

curl -X POST https://api.scalebox.dev/v1/sandboxes/sbx-abc123def456789/resume \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{
    "is_async": false,
    "object_storage": {
      "mounts": [
        { "mount_point": "/mnt/oss-extra", "delete": true }
      ]
    }
  }'

Terminate Sandbox

POST /v1/sandboxes/{sandbox_id}/terminate

Force terminate a sandbox immediately.

Success response

Usually 202 Accepted with top-level message: "Sandbox termination initiated" and:

• data.sandbox_id
• data.status - termination_in_progress
• data.note

Special case: if the sandbox is already terminated, the backend returns 200 OK with data.sandbox_id, data.status: "terminated", data.note, and top-level message: "Sandbox is already terminated".

Example

curl -X POST https://api.scalebox.dev/v1/sandboxes/sbx-abc123def456789/terminate \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"

Proxied Command Exec (Run Command)

Run a single shell command in a running sandbox and stream output over SSE. This feature is channel-oriented:

• One command at a time per sandbox (server enforces concurrency).
• The stream buffer is current-run only (not a command history) and is purged when the runner stops.
• Output is streamed as events; clients may merge stdout and stderr and render it like a terminal.

Start Command Exec

POST /v1/sandboxes/{sandbox_id}/exec

Request body

Success response

Raw 201 Created JSON (no standard envelope):

• stream_path - relative SSE path to attach to
• started_at - RFC3339Nano UTC string
• deadline - RFC3339Nano UTC string for the hard wall-clock limit

Example

curl -X POST https://api.scalebox.dev/v1/sandboxes/sbx-abc123def456789/exec \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{"command":"ls -la /tmp","cwd":"/","env":{}}'

Stream Exec Output (SSE)

GET /v1/sandboxes/{sandbox_id}/exec/stream?token=...

Browser EventSource cannot send custom headers, so browsers authenticate using the token query parameter. Non-browser clients (curl/CLI/server-to-server) may authenticate using X-API-Key instead.

Success response

200 OK as text/event-stream. The server first emits a ready event, then zero or more start, stdout, stderr, or keepalive events, and finally an end or error event.

Example (curl)

curl -N "https://api.scalebox.dev/v1/sandboxes/sbx-abc123def456789/exec/stream?token=$ACCESS_TOKEN"

Example (curl with API key header)

curl -N "https://api.scalebox.dev/v1/sandboxes/sbx-abc123def456789/exec/stream" \
  -H "X-API-Key: sk-..."

Event types

• ready: stream is attached
• start: process started (includes pid)
• stdout: base64 chunk (data_b64)
• stderr: base64 chunk (data_b64)
• keepalive: keep connection alive
• end: process exited (includes exit_code)
• error: terminal error (includes code, message)

Check If Exec Is Active

GET /v1/sandboxes/{sandbox_id}/exec/active

Returns active: true plus stream_path, command, cwd, started_at, deadline when a command is currently running for this sandbox (same user).

Success response

Raw 200 OK JSON (no standard envelope):

• idle: { "active": false }
• active: { "active": true, "stream_path": "...", "command": "...", "cwd": "/", "started_at": "...", "deadline": "..." }

Cancel Current Exec

DELETE /v1/sandboxes/{sandbox_id}/exec

Cancels the currently running command for this sandbox.

Success response

Raw 200 OK JSON: { "cancelled": true }

Stream buffering notes

The exec output stream is a short-lived, best-effort channel for the current run. Output events may be truncated and older buffered events may be dropped when limits are reached.

Batch Delete

POST /v1/sandboxes/batch-delete

Delete multiple sandboxes in batch.

Request Parameters

Success response

202 Accepted with top-level message summarizing counts and:

• data.total
• data.successful
• data.failed
• data.results: array of { sandbox_id, status, error? }

Example

curl -X POST https://api.scalebox.dev/v1/sandboxes/batch-delete \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{
    "sandbox_ids": ["sbx-abc123def456789", "sbx-def456ghi789012"],
    "force": false
  }'

Batch Terminate

POST /v1/sandboxes/batch-terminate

Terminate multiple sandboxes concurrently (up to 50 processed simultaneously).

Request Parameters

Success response

202 Accepted with top-level message summarizing counts and:

• data.total
• data.successful
• data.failed
• data.results: array of { sandbox_id, status, error? }

Batch Pause

POST /v1/sandboxes/batch-pause

Pause multiple running sandboxes concurrently.

Request Parameters

Success response

202 Accepted with top-level message summarizing counts and:

• data.total
• data.successful
• data.failed
• data.results: array of { sandbox_id, status, error? }

Batch Resume

POST /v1/sandboxes/batch-resume

Resume multiple paused sandboxes concurrently with budget and subscription validation.

Request Parameters

Success response

202 Accepted with top-level message summarizing counts and:

• data.total
• data.successful
• data.failed
• data.results: array of { sandbox_id, status, error? }

Update Timeout

POST /v1/sandboxes/{sandbox_id}/timeout

Update sandbox timeout independently.

Request Parameters

Success response

200 OK with a context-specific top-level message and:

• data.timeout
• data.timeout_at
• data.remaining_time
• data.applies_to - current_phase or next_phase
• data.note

Example

curl -X POST https://api.scalebox.dev/v1/sandboxes/sbx-abc123def456789/timeout \
  -H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{"timeout": 7200}'

Switch Project

POST /v1/sandboxes/{sandbox_id}/switch-project

Move a sandbox to a different project.

Request Parameters

Success response

200 OK with top-level message: "Sandbox project switched successfully". No data object is returned.

Get Metrics

GET /v1/sandboxes/{sandbox_id}/metrics

Get raw sandbox performance metrics with time-series data.

Request Parameters

Success response

200 OK in the standard envelope with:

• data.sandbox_id
• data.timestamp
• data.status
• data.uptime_seconds
• data.metrics: array of { timestamp, cpu_count, cpu_used_pct, disk_total, disk_used, mem_total, mem_used }
• data.error: optional string when the sandbox has no runtime metrics available

Get Metrics Chart

GET /v1/sandboxes/{sandbox_id}/metrics/chart

Get chart-optimized metrics data for frontend visualization.

Request Parameters

Success response

200 OK in the standard envelope with:

• data.sandbox_id
• data.status
• data.time_window
• data.chart_config
• data.metrics - map of chart series, typically including cpu_usage, memory_usage, and disk_usage
• optional data.reference_limits

Get Stats

GET /v1/sandboxes/stats

Get sandbox statistics and usage data.

Success response

200 OK in the standard envelope with:

• data.total_sandboxes
• data.running_sandboxes
• data.terminated_sandboxes
• data.failed_sandboxes
• data.avg_cpu_usage
• data.avg_memory_usage
• data.total_uptime_hours

Create Template from Sandbox

POST /v1/sandboxes/{sandbox_id}/create-template

Create a template from a running sandbox. The sandbox must be in 'running' state.

Request Parameters

Success response

200 OK in the standard envelope with:

• data.template_id
• data.name
• data.description
• data.default_cpu_count
• data.default_memory_mb
• data.visibility
• data.status
• data.harbor_project
• data.harbor_repository
• data.harbor_tag
• data.base_template_id
• data.ports
• data.custom_command
• data.ready_command
• data.created_at
• data.message

Even though this returns 200 OK, the backend message makes clear the image push/template finalize step continues asynchronously.

Get Sandbox Ports

GET /v1/sandboxes/{sandbox_id}/ports

Get all ports for a sandbox (template ports + custom ports).

Success response

200 OK in the standard envelope with:

• data.ports
• data.template_ports
• data.custom_ports

Add Sandbox Port

POST /v1/sandboxes/{sandbox_id}/ports

Add a custom port to a running sandbox.

Request Parameters

Success response

200 OK with top-level message: "Port added successfully" and data.port, a port object containing port, service_port, protocol, name, and is_protected.

Remove Sandbox Port

DELETE /v1/sandboxes/{sandbox_id}/ports/{port}

Remove a custom port from a running sandbox.

Success response

200 OK with top-level message: "Port removed successfully". No data object is returned.

Get WebRTC TURN Credential

GET /v1/sandboxes/{sandbox_id}/webrtc-turn-credential

Get short-lived TURN credentials for a sandbox. The sandbox must be running and have at least one WebRTC port.

Success response

200 OK in the standard envelope with:

• data.ice_servers
• data.username
• data.credential
• data.turn_public_host
• data.turn_public_port

Object Storage

ScaleBox supports mounting S3-compatible object storage into sandboxes using FUSE. You can configure object storage at sandbox creation time, or mount it manually at runtime.

Object Storage Configuration

Mount metadata in responses: GET sandbox responses include object_storage as an array of slot records: slot, state (active, disabled, or free), uri, mount_point, optional region/endpoint, and short_lived when the mount uses temporary credentials. Credentials are never included.

Temporary (STS) credentials

Provide session_token with access key and secret key from AWS STS (or compatible providers). The mount is treated as short-lived: session tokens expire and must be supplied again when resuming a paused sandbox (via an object_storage upsert on single-sandbox resume). Omit session_token on a resume upsert to convert the mount back to a standard long-lived credential mount.

Batch resume does not accept an OSS patch. Sandboxes with active short-lived mounts require single-sandbox resume with fresh credentials (or best_effort_oss: true).

Object Storage Resume Patch

While a sandbox is paused, POST /v1/sandboxes/{sandbox_id}/resume accepts an optional object_storage delta. This works whether the sandbox already has mounts or not — upsert entries can add the first mount on resume. Send only changed mounts; the backend merges by mount_point into persistent slot records.

Specify exactly one patch mode:

mounts[] entries (keyed by mount_point):

• Upsert (default): include uri, access_key, secret_key, and at least one of region or endpoint (same validation as create). Include session_token when refreshing temporary credentials or creating a short-lived mount.
• Delete: { "mount_point": "/mnt/x", "delete": true } — do not include uri/credentials.
• Disable: { "mount_point": "/mnt/x", "disable": true } — do not include uri/credentials.

When resuming without changing mounts, standard (non-short-lived) sandboxes do not need to re-enter credentials. Temporary mounts require an upsert with fresh credentials unless best_effort_oss is set.

Ambiguous requests (e.g. remove_all + mounts, delete with credentials, unknown mount_point) return HTTP 400.

Example (add first mount on resume):

curl -X POST https://api.scalebox.dev/v1/sandboxes/sbx-abc123/resume \
  -H "X-API-Key: sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "object_storage": {
      "mounts": [{
        "mount_point": "/mnt/data",
        "uri": "s3://my-bucket/data/",
        "access_key": "AKIA...",
        "secret_key": "...",
        "region": "us-east-1"
      }]
    }
  }'

Example (refresh temporary credentials on resume):

curl -X POST https://api.scalebox.dev/v1/sandboxes/sbx-abc123/resume \
  -H "X-API-Key: sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "object_storage": {
      "mounts": [{
        "mount_point": "/mnt/oss",
        "uri": "s3://my-bucket/data/",
        "access_key": "ASIA...",
        "secret_key": "...",
        "session_token": "...",
        "region": "us-east-1"
      }]
    }
  }'

Example (best-effort resume without OSS patch):

curl -X POST https://api.scalebox.dev/v1/sandboxes/sbx-abc123/resume \
  -H "X-API-Key: sk-..." \
  -H "Content-Type: application/json" \
  -d '{"best_effort_oss": true}'

Manual Mounting at Runtime

All sandboxes have FUSE capabilities enabled. You can manually mount object storage:

# Create credentials file
echo "ACCESS_KEY:SECRET_KEY" > /root/.s3fs-credentials
chmod 600 /root/.s3fs-credentials

# Create mount point
mkdir -p /mnt/oss

# Mount S3 bucket
s3fs bucket-name:/path /mnt/oss \
  -o passwd_file=/root/.s3fs-credentials \
  -o url=https://s3.region.amazonaws.com \
  -o endpoint=region

Metrics API

The sandbox metrics API provides real-time performance data and historical trends for monitoring resource utilization.

Metrics Endpoints

Raw Metrics: /v1/sandboxes/{sandbox_id}/metrics

• Returns standardized time-series metrics optimized for API consumers
• Data Format: Array of timestamped metrics with CPU, memory, and disk usage
• Use Cases: Monitoring, alerting, data analysis, integration with external tools

Chart Metrics: /v1/sandboxes/{sandbox_id}/metrics/chart

• Returns chart-ready data optimized for frontend visualization
• Features: Built-in statistics, trend analysis, color schemes, and chart configuration
• Use Cases: Dashboard widgets, real-time monitoring, performance analytics

Time Parameters

Resource Metrics

Error Handling

Best Practices

HTTP Status Codes