ScaleBox Sandbox Skill

Create and manage isolated cloud sandboxes for secure code execution.

When to Use

• Running untrusted code in an isolated environment
• Browser automation (browser-use, computer-use templates)
• Testing scripts that may have side effects
• Remote code execution without local resource impact
• Creating temporary development environments

Prerequisites

1. Get API Key

Register at ScaleBox Dashboard to get your API key.

Set environment variable:

export SCALEBOX_API_KEY="your-api-key-here"

2. Install CLI

Download the official CLI from ScaleBox Documentation:

# Visit official docs for platform-specific downloads
# https://www.scalebox.dev/docs/en/cli/installation

# After installation, authenticate:
scalebox-cli auth login --api-key $SCALEBOX_API_KEY --server-url https://api.scalebox.dev

Security Note: Always download CLI from official sources. Verify checksums when available.

3. Server URL

https://api.scalebox.dev

Port Access URL Format

Important: ScaleBox uses port prefixes, not port suffixes.

Method 1: Specify ports at creation time (Recommended)

Use API to specify custom_ports when creating the sandbox:

curl -X POST "https://api.scalebox.dev/v1/sandboxes" \
  -H "X-API-Key: $SCALEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "base",
    "name": "my-sandbox",
    "timeout": 3600,
    "custom_ports": [
      {"port": 8080, "name": "web-server", "protocol": "TCP"}
    ]
  }'

Method 2: Add port to running sandbox

If you need to add a port after creation:

# CLI
scalebox-cli sandbox port add <sandbox-id> --port 8080 --name web-server --protocol TCP

# API
curl -X POST "https://api.scalebox.dev/v1/sandboxes/{sandbox_id}/ports" \
  -H "X-API-Key: $SCALEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080, "name": "web-server", "protocol": "TCP"}'

Access URL Format

Format: https://{port}-{sandbox_domain}/path

Example:

• Sandbox domain: sbx-abc123.k27xn5o3lnw5dan3x.scalebox.dev
• Port: 8080
• Correct URL: https://8080-sbx-abc123.k27xn5o3lnw5dan3x.scalebox.dev/
• ❌ Wrong: https://sbx-abc123.k27xn5o3lnw5dan3x.scalebox.dev:8080/

Available Templates

Three Ways to Use ScaleBox

Method 1: CLI Commands

1.1 Sandbox Lifecycle

# Create sandbox
scalebox-cli sandbox create --template <name> --name <name> --timeout <seconds>

# List sandboxes
scalebox-cli sandbox list

# Get sandbox details
scalebox-cli sandbox get <sandbox-id>

# Pause sandbox (preserves state)
scalebox-cli sandbox pause <sandbox-id>

# Resume paused sandbox
scalebox-cli sandbox resume <sandbox-id>

# Terminate sandbox immediately
scalebox-cli sandbox terminate <sandbox-id>

# Delete sandbox and resources
scalebox-cli sandbox delete <sandbox-id>

Create parameters:

• --template: Template name or ID (default: base)
• --name: Sandbox name (optional, auto-generated)
• --timeout: Timeout in seconds (default: 300)
• --cpu: CPU count (minimum: 2)
• --memory: Memory in MB
• --storage: Storage in GB
• --async: Fire-and-forget mode - returns immediately, sandbox may still be starting. You must poll status yourself.
• --auto-pause: Pause on timeout instead of terminate

Important: async vs sync:

• Sync mode (default, no --async): Waits for sandbox to be fully running before returning. The returned sandbox is ready to use.
• Async mode (--async): Returns immediately after creating the request. The sandbox may still be starting. You must poll sandbox get until status: running before using it.

# Sync mode (recommended) - sandbox is ready when command returns
scalebox-cli sandbox create --template base --timeout 600
# Output includes sandbox ID, ready to use

# Async mode - need to wait
scalebox-cli sandbox create --template base --timeout 600 --async
# Returns immediately, sandbox may still be starting
# Must poll: scalebox-cli sandbox get <id> until status is "running"

1.2 File Operations

# Upload file
scalebox-cli sandbox upload <sandbox-id> <local-path> <remote-path>

# Upload directory recursively
scalebox-cli sandbox upload <sandbox-id> ./project /workspace/project --recursive

# Download file
scalebox-cli sandbox download <sandbox-id> <remote-path> <local-path>

# List files
scalebox-cli sandbox ls <sandbox-id> <remote-path>

Note: Remote path must be absolute (e.g., /workspace/file.py).

1.3 Command Execution

# Execute command
scalebox-cli sandbox exec <sandbox-id> "<command>"

# With working directory
scalebox-cli sandbox exec <sandbox-id> "python3 script.py" --cwd /workspace

# With timeout
scalebox-cli sandbox exec <sandbox-id> "npm install" --timeout 120

Method 2: REST API

2.1 Authentication

All requests require X-API-Key header:

curl -H "X-API-Key: $SCALEBOX_API_KEY" https://api.scalebox.dev/v1/sandboxes

2.2 Sandbox Endpoints

Note: File operations (upload/download/exec) are only available via CLI or SDK.

2.3 API Example

# Create sandbox
curl -X POST "https://api.scalebox.dev/v1/sandboxes" \
  -H "X-API-Key: $SCALEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template": "base", "name": "my-sandbox", "timeout": 600}'

Method 3: Python SDK

3.1 Installation

pip install scalebox-sdk

Module name: scalebox (not scalebox_sdk)

3.2 Basic Usage

import scalebox
import os

# Create sandbox
sandbox = scalebox.Sandbox.create(
    template="base",
    timeout=600,
    api_key=os.environ.get("SCALEBOX_API_KEY")
)

print(f"Sandbox ID: {sandbox.sandbox_id}")

# Get signed URLs for file operations
upload_url = sandbox.upload_url(path="/workspace/test.py")
download_url = sandbox.download_url(path="/workspace/output.json")

# Kill sandbox
sandbox.kill()

Typical Workflow

# 1. Create sandbox
sandbox_id=$(scalebox-cli sandbox create --template code-interpreter --name my-task --async | grep "Sandbox ID:" | awk '{print $3}')

# 2. Upload code
scalebox-cli sandbox upload $sandbox_id ./script.py /workspace/script.py

# 3. Execute
scalebox-cli sandbox exec $sandbox_id "python3 /workspace/script.py"

# 4. Download results
scalebox-cli sandbox download $sandbox_id /workspace/output.json ./output.json

# 5. Cleanup
scalebox-cli sandbox delete $sandbox_id

Security Notes

• Sandboxes are completely isolated from local machine
• All file paths must be absolute (no .. traversal)
• Internet access enabled by default (disable with --internet=false)
• Credentials never stored in database
• Minimum CPU: 2 cores
• Always download CLI from official sources

Error Handling

Links

• Official Website: https://www.scalebox.dev
• Documentation: https://www.scalebox.dev/docs
• CLI Installation: https://www.scalebox.dev/docs/en/cli/installation
• API Reference: https://www.scalebox.dev/docs/en/api

Version

• Skill: 1.0.5
• CLI: v1.3.4
• SDK: v0.1.9
• API: v1

Last updated: 2026-03-21