Sandbox API

Complete API reference for managing sandbox environments. Sandboxes are isolated development environments that you can create, configure, and manage through the ScaleBox API.

Authentication: Most sandbox APIs require the X-API-Key header.

Exception: GET /v1/scalebox-regions is public (key optional). Use it to list region ids before setting locality.region on create.

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:

Status	Description
`created`	Sandbox has been created but not started
`starting`	Sandbox is being started and resources are being allocated (substatus: allocating, deploying, initializing, waiting_ready)
`running`	Sandbox is running and accessible
`terminating`	Sandbox is being terminated and resources are being cleaned up (substatus: cleaning_resources, cleaning_data)
`terminated`	Sandbox has been terminated and cannot be restarted
`failed`	Sandbox encountered an error during creation or operation

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

Name	Type	Required	Default	Description
name	string	No	Auto-generated	Human-readable sandbox name (0-24 characters)
description	string	No	Empty	Detailed description of the sandbox purpose
template	string	No	"base"	Template name or ID (e.g., "python-dev" or "tpl-abc123")
project_id	string	No	User's default	Project to associate the sandbox with
cpu_count	integer	No	Template default	Number of CPU cores
memory_mb	integer	No	Template default	Memory allocation in megabytes
storage_gb	integer	No	50% of plan max	Persistent storage in gigabytes
timeout	integer	No	300	Sandbox timeout in seconds
env_vars	object	No		Environment variables to set in the sandbox
metadata	object	No		Custom key-value pairs for sandbox metadata
secure	boolean	No	true	Security setting for the sandbox
allow_internet_access	boolean	No	true	Whether to allow internet access from the sandbox
object_storage	object/array	No	null	One mount (JSON object) or multiple mounts (JSON array)
object_storage_direct_mount	boolean	No	false	Custom templates only: mount object storage in the worker container
s3fs_executable_path	string	No	Empty	When using direct mount: optional path to the s3fs binary
custom_ports	array	No	[]	Array of custom port configurations
locality	object	No	null	Optional scheduling: `{ auto_detect: true }` and/or `{ region: string, force?: boolean }`
auto_pause	boolean	No	false	When true, sandbox timeout triggers auto-pause instead of termination
is_async	boolean	No	false	When true, return immediately (client polls for status)

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.

Example

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

List Sandboxes

GET /v1/sandboxes

List all sandboxes for the authenticated user.

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.

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

Name	Type	Required	Description
timeout	integer	Yes	New timeout in seconds (must be greater than current timeout)

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.

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

Name	Type	Required	Default	Description
is_async	boolean	No	false	When true, return immediately (client polls)

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

Name	Type	Required	Default	Description
is_async	boolean	No	false	When true, return immediately (client polls)

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

Terminate Sandbox

POST /v1/sandboxes/{sandbox_id}/terminate

Force terminate a sandbox immediately.

Example

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

Batch Delete

POST /v1/sandboxes/batch-delete

Delete multiple sandboxes in batch.

Request Parameters

Name	Type	Required	Default	Description
sandbox_ids	array	Yes	-	Array of sandbox IDs to delete (max 100)
force	boolean	No	false	Force delete even if running

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

Name	Type	Required	Default	Description
sandbox_ids	array	Yes	-	Array of sandbox IDs to terminate (max 100)
force	boolean	No	false	Force terminate even if in transitional states

Batch Pause

POST /v1/sandboxes/batch-pause

Pause multiple running sandboxes concurrently.

Request Parameters

Name	Type	Required	Description
sandbox_ids	array	Yes	Array of sandbox IDs to pause (max 100)

Batch Resume

POST /v1/sandboxes/batch-resume

Resume multiple paused sandboxes concurrently with budget and subscription validation.

Request Parameters

Name	Type	Required	Description
sandbox_ids	array	Yes	Array of sandbox IDs to resume (max 100)

Update Timeout

POST /v1/sandboxes/{sandbox_id}/timeout

Update sandbox timeout independently.

Request Parameters

Name	Type	Required	Description
timeout	integer	Yes	New timeout in seconds

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

Name	Type	Required	Description
project_id	string	Yes	Target project ID to move the sandbox to

Get Metrics

GET /v1/sandboxes/{sandbox_id}/metrics

Get raw sandbox performance metrics with time-series data.

Request Parameters

Name	Type	Required	Default	Description
start	string	No	5 minutes ago	Start time in ISO 8601, RFC3339, or Unix timestamp format
end	string	No	now	End time in ISO 8601, RFC3339, or Unix timestamp format
step	integer	No	5	Time step in seconds between data points

Get Metrics Chart

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

Get chart-optimized metrics data for frontend visualization.

Request Parameters

Name	Type	Required	Default	Description
start	string	No	5 minutes ago	Start time
end	string	No	now	End time
step	string	No	5s	Time step as duration string (e.g., '15m', '5s', '1h')

Get Stats

GET /v1/sandboxes/stats

Get sandbox statistics and usage data.

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

Name	Type	Required	Description
name	string	Yes	Template name (4-32 characters)
description	string	No	Detailed description of the template
visibility	string	No	Template visibility: 'private', 'account_shared', or 'public'
cpu_count	integer	No	Default CPU cores (nil/omit = inherit)
memory_mb	integer	No	Default memory in MB (nil/omit = inherit)
ports	string	No	JSON array of additional port configurations
custom_command	string	No	Custom start command for the template
ready_command	string	No	Readiness probe JSON

Get Sandbox Ports

GET /v1/sandboxes/{sandbox_id}/ports

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

Add Sandbox Port

POST /v1/sandboxes/{sandbox_id}/ports

Add a custom port to a running sandbox.

Request Parameters

Name	Type	Required	Default	Description
port	integer	Yes	-	Port number (1-65535)
name	string	Yes	-	Port name (must be unique, max 15 characters)
protocol	string	No	TCP	Protocol (TCP, UDP, or WEBRTC)
service_port	integer	No	Same as port	Service port number

Remove Sandbox Port

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

Remove a custom port from a running sandbox.

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.

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

Field	Type	Required	Description
uri	string	Yes	S3-compatible storage URI: `s3://bucket-name/path` or `oss://bucket-name/path`
mount_point	string	Yes	Absolute path in the container where the storage will be mounted
access_key	string	Yes	S3 access key ID. Credentials are never stored or returned
secret_key	string	Yes	S3 secret access key. Credentials are never stored or returned
region	string	No	S3 region string (e.g., `us-east-1`). At least one of region or endpoint required
endpoint	string	No	Custom S3-compatible endpoint URL

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

Security Note: Object storage credentials are never persisted in the database. Only the URI and mount point are stored and returned in API responses.

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

Parameter	Description
`start`	Start time for the metrics query. Supports ISO 8601, RFC3339, and Unix timestamp
`end`	End time for the metrics query. Defaults to current time
`step`	Time interval between data points. Raw: seconds, Chart: duration string ('15m', '5s')

Resource Metrics

Metric	Description
CPU	Requested cores (integer) and usage percentage (0-100)
Memory	Requested and used memory in bytes
Storage	Requested and used disk space in bytes
Uptime	Sandbox running time in seconds

Error Handling

Scenario	Description
No Data Available	Returns empty metrics array with status when sandbox is not running
Invalid Time Range	Automatically swaps start/end times if they're in wrong order
Resource Not Found	Returns 404 if sandbox doesn't exist or user lacks access

Best Practices

Practice	Description
Time Range Selection	Use appropriate step sizes: 5-30 seconds for real-time, 1-15 minutes for historical
Data Polling	Poll metrics every 30-60 seconds for live dashboards
Error Handling	Always check the response status and handle cases where metrics data is unavailable

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Too Many Requests
500	Internal Server Error

Sandbox API

On this page