Sandbox Commands

Complete reference for managing sandbox environments using the ScaleBox CLI.

sandbox list

List sandboxes with pagination or fetch the full result set.

Flags

Examples

scalebox-cli sandbox list
scalebox-cli sandbox list --page 2 --limit 10
scalebox-cli sandbox list --all
scalebox-cli sandbox list --all --max-items 200
scalebox-cli -o json sandbox list --page 1 --limit 10

Do not combine --all with a non-default --page. JSON output uses a nested pagination object.

Secure HTTPS File Operations (v1.2.2)

All file transfer operations now use secure HTTPS protocol with smart conflict detection and strict path validation. Supports public and private sandbox routing. Remote paths are absolute paths in the sandbox (e.g. /workspace, /home/jovyan); directory traversal (..) is not allowed.

sandbox upload

Upload files or directories to sandbox with smart conflict detection.

scalebox-cli sandbox upload sbx-abc123 ./myfile.txt /workspace/myfile.txt

sandbox download

Download files or directories from sandbox.

scalebox-cli sandbox download sbx-abc123 /workspace/results.json ./results.json

sandbox ls

List directory contents with detailed information.

scalebox-cli sandbox ls sbx-abc123 /workspace

sandbox create

Sync (default): waits until running, then connects to the interactive terminal unless --no-terminal (CI/scripts). --async: API returns immediately; the CLI does not poll—use scalebox-cli sandbox get <id> for status.

Basic usage:

scalebox-cli sandbox create --template tpl-abc123 --name my-workspace

With auto-pause (pauses on timeout instead of terminating):

scalebox-cli sandbox create --template tpl-abc123 --name my-workspace --timeout 3600 --auto-pause

Async create (no CLI polling):

scalebox-cli sandbox create --template tpl-abc123 --name my-workspace --async

Sync create without interactive terminal:

scalebox-cli sandbox create --template tpl-abc123 --name my-workspace --no-terminal

The --auto-pause flag enables automatic pausing when the sandbox reaches its timeout, instead of the default termination behavior. This is useful for development environments that you want to preserve but don't need running continuously.

Regions (scheduling): run scalebox-cli sandbox regions (or --json) to list ids, then --locality-region, optional --locality-force, or --locality-auto-detect. If the regions list is non-empty, the CLI rejects unknown ids before create.

Object storage & custom ports: inline JSON only (same style as create-template --ports): --object-storage accepts one object or a JSON array for multiple mounts; --ports is a JSON array for custom_ports. Optional --object-storage-direct-mount and --s3fs-executable-path for custom templates.

scalebox-cli sandbox regions

scalebox-cli sandbox create --template base --name demo --locality-region ap-southeast --object-storage '{"uri":"s3://b/p","mount_point":"/mnt/oss","access_key":"KEY","secret_key":"SECRET","region":"us-east-1"}'
scalebox-cli sandbox create --object-storage '{"uri":"s3://b/p","mount_point":"/mnt/oss","access_key":"ASIA...","secret_key":"SECRET","session_token":"...","region":"us-east-1"}'

Sandbox Lifecycle Management (v1.3.0)

Manage sandbox state with pause, resume, terminate, and delete operations. Pause and resume are synchronous by default (CLI waits until complete); use --async to return immediately and poll yourself. Create behavior is described above (--async / --no-terminal). Single and batch modes apply where documented.

sandbox pause

Pause one or more running sandboxes to save resources while preserving their state. By default the command waits until paused; use --async to return immediately.

Single sandbox:

scalebox-cli sandbox pause sbx-abc123

Batch pause (multiple sandboxes):

scalebox-cli sandbox pause sbx-abc123 sbx-def456 sbx-ghi789

sandbox resume

Resume one or more paused sandboxes to restore them to running state. By default the command waits until running; use --async to return immediately.

Single-sandbox resume supports an optional OSS delta via --object-storage (JSON with remove_all, disable_all, or mounts[]) and --best-effort-oss. Not supported when resuming multiple IDs.

Single sandbox:

scalebox-cli sandbox resume sbx-abc123

Resume with OSS patch (single sandbox):

scalebox-cli sandbox resume sbx-abc123 --object-storage '{"mounts":[{"mount_point":"/mnt/oss","uri":"s3://bucket/p","access_key":"AK","secret_key":"SK","region":"us-east-1"}]}'

Resume with fresh temporary (STS) credentials:

scalebox-cli sandbox resume sbx-abc123 --object-storage '{"mounts":[{"mount_point":"/mnt/oss","uri":"s3://bucket/p","access_key":"ASIA...","secret_key":"SK","session_token":"...","region":"us-east-1"}]}'

Best-effort resume (mount failures do not block resume):

scalebox-cli sandbox resume sbx-abc123 --best-effort-oss

Batch resume (multiple sandboxes):

scalebox-cli sandbox resume sbx-abc123 sbx-def456 sbx-ghi789

sandbox terminate

Terminate one or more sandboxes immediately.

Single sandbox:

scalebox-cli sandbox terminate sbx-abc123

Batch terminate (multiple sandboxes):

scalebox-cli sandbox terminate sbx-abc123 sbx-def456 sbx-ghi789 --force

sandbox delete

Delete one or more sandboxes and release all associated resources.

Single sandbox:

scalebox-cli sandbox delete sbx-abc123

Batch delete (multiple sandboxes):

scalebox-cli sandbox delete sbx-abc123 sbx-def456 sbx-ghi789 --force

Template Creation from Sandbox (v1.2.8)

Create reusable templates from running sandboxes. This captures the current state of a sandbox and allows you to create new sandboxes with the same configuration.

sandbox create-template

Create a new template from a running sandbox.

Basic usage:

scalebox-cli sandbox create-template sbx-abc123 --name my-template

With custom configuration:

scalebox-cli sandbox create-template sbx-abc123 --name my-template --description "Custom template" --cpu 4 --memory 8192

Available flags:

• --name (required): Template name (4-32 characters, lowercase letters, numbers, hyphens, and underscores)
• --description: Template description
• --public: Make template public (admin only)
• --cpu: CPU count (0 = inherit from base template)
• --memory: Memory in MB (0 = inherit from base template)
• --ports: Additional ports (JSON array format)
• --start-command: Custom start command
• --ready-command: Readiness probe JSON (type exec|httpGet|tcpSocket) or plain command (exec)

WebRTC TURN & Port Management (v1.3.3)

For sandboxes with a WebRTC port, fetch short-lived TURN credentials for RTCPeerConnection. Manage custom ports on running sandboxes with sandbox port list, port add, and port remove. For in-sandbox environment variables (e.g. TURN_CREDENTIAL_SERVICE_URL, TURN_PUBLIC_HOST) and how to host WebRTC apps, see the guide WebRTC in Sandboxes.

sandbox webrtc-credential

Fetch TURN credentials (ice_servers, username, credential) for a sandbox. The sandbox must be running and have a WebRTC port. Output is JSON.

scalebox-cli sandbox webrtc-credential sbx-abc123

sandbox port list

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

scalebox-cli sandbox port list sbx-abc123

sandbox port add

Add a custom port to a running sandbox. Use --port and --name (required). Optional: --protocol (TCP, UDP, WEBRTC), --service-port.

scalebox-cli sandbox port add sbx-abc123 --port 8080 --name api

scalebox-cli sandbox port add sbx-abc123 --port 9000 --name webrtc --protocol WEBRTC

sandbox port remove

Remove a custom port from a running sandbox. Only custom (non-template) ports can be removed.

scalebox-cli sandbox port remove sbx-abc123 8080

Object Storage Mounting

ScaleBox supports mounting S3-compatible object storage into sandboxes. You can configure object storage when creating a sandbox, or mount it manually at runtime. All sandboxes have FUSE capabilities enabled by default.

Creating Sandbox with Object Storage

Configure object storage when creating a sandbox using --object-storage (inline JSON) or the API. The storage will be automatically mounted when the sandbox starts.

Optional session_token for AWS STS temporary credentials marks the mount as short-lived in API responses. Temporary credentials must be supplied again when resuming a paused sandbox (single-sandbox resume with an OSS upsert). Credentials are never stored or returned.

scalebox-cli sandbox create --object-storage '{"uri":"s3://my-bucket/data","mount_point":"/mnt/oss","access_key":"YOUR_KEY","secret_key":"YOUR_SECRET","region":"us-east-1"}'

scalebox-cli sandbox create --object-storage '{"uri":"s3://my-bucket/data","mount_point":"/mnt/oss","access_key":"ASIA...","secret_key":"YOUR_SECRET","session_token":"...","region":"us-east-1"}'

Manual Mounting at Runtime

All sandboxes have FUSE capabilities enabled. You can manually mount object storage by executing commands in the running container:

# Create credentials file
echo "YOUR_ACCESS_KEY:YOUR_SECRET_KEY" > /root/.s3fs-credentials
chmod 600 /root/.s3fs-credentials

# Create mount point
mkdir -p /mnt/oss

# Mount S3 bucket (for non-default regions, specify both url and endpoint)
s3fs bucket-name:/path /mnt/oss \
  -o passwd_file=/root/.s3fs-credentials \
  -o url=https://s3.region.amazonaws.com \
  -o endpoint=region

HTTPS Security & Path Requirements

ScaleBox CLI v1.2.2 uses HTTPS secure communication and enforces strict path validation for security and clarity:

✅ Valid Paths

• /workspace/myfile.txt - Workspace directory
• /home/user/document.pdf - User home directory
• /tmp/data.json - System temporary directory
• /etc/config.conf - System configuration files
• / - Root directory

❌ Invalid Paths

• ../etc/passwd - Directory traversal attack
• /../../etc/shadow - Path traversal attempt
• myfile.txt - Relative path (use absolute paths)
• workspace/file.txt - Missing leading slash

Command Flags

Available flags for enhanced control over file operations:

--force

Overwrite existing files without confirmation. Use with upload/download to overwrite conflicting files.

--recursive

Transfer directories recursively. Required when uploading/downloading directories.