Cloudsway ScaleBox Sandbox

Dev Tools

Create and manage isolated cloud sandboxes for secure, remote code execution, browser automation, and temporary development environments via CLI, API, or Pyt...

Install

openclaw skills install cloudsway-scalebox-sandbox

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

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

Template	CPU	Memory	Use Case
base	2	512MB	Basic sandbox
code-interpreter	2	1GB	Jupyter environment
browser-use	2	2GB	Browser automation (VNC)
browser-use-headless	4	4GB	Browser automation (headless)
desktop	8	8GB	Desktop environment (VNC)
computer-use-preview	2	2GB	Google Computer Use

Three Ways to Use ScaleBox

Method	Best For	Notes
CLI	File operations, command execution	Most powerful, cross-platform
REST API	Lifecycle management	Auth via `X-API-Key` header
Python SDK	Programmatic access	`pip install scalebox-sdk`

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 <id> 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

Operation	Method	Endpoint
Create sandbox	POST	`/v1/sandboxes`
List sandboxes	GET	`/v1/sandboxes`
Get sandbox	GET	`/v1/sandboxes/{id}`
Delete sandbox	DELETE	`/v1/sandboxes/{id}`
Pause sandbox	POST	`/v1/sandboxes/{id}/pause`
Resume sandbox	POST	`/v1/sandboxes/{id}/resume`

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

Error	Solution
`CPU count must be at least 2`	Use `--cpu 2` or higher
`health check timeout`	Check status with `sandbox get`
`Sandbox not found`	Verify sandbox ID
`Timeout exceeded`	Create new sandbox

Version

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

Last updated: 2026-03-21