Sandbank
Cloud

# Default: Lightpanda (fast, in-sandbox)
browser open https://docs.example.com
browser snapshot -i              # accessibility tree with refs
browser click @e2                # interact by ref
browser screenshot               # save PNG to /tmp/screenshot.png

# Chrome mode: real browser for complex sites
browser open --chrome https://app.example.com/login
browser fill @e1 "[email protected]"
browser fill @e2 "password"
browser click @e3                # submit login
browser screenshot               # visual confirmation
browser save logged-in           # snapshot VM state
browser destroy                  # back to Lightpanda

# db9 CLI is pre-installed in every codebox

# Create a database (zero-setup trial on first use)
db9 db create --name myapp

# Execute SQL
db9 db sql myapp -q "CREATE TABLE users (id serial, name text, email text)"
db9 db sql myapp -q "INSERT INTO users (name, email) VALUES ('Alice', '[email protected]')"

# Vector search with pgvector
db9 db sql myapp -q "CREATE EXTENSION vector"
db9 db sql myapp -q "ALTER TABLE users ADD COLUMN embedding vector(1536)"

# Branch a database for isolated testing
db9 branch create myapp --name experiment

# Or connect directly with psql
psql $DATABASE_URL -c "SELECT * FROM users"

# Create a sandbox — x402 payment is handled automatically
# The server returns 402 with payment details, your x402 client pays and retries
curl -X POST https://api.sandbank.dev/v1/boxes \
  -H "Content-Type: application/json" \
  -d '{"image": "codebox", "cpu": 2, "memory_mb": 1024}'

# → {"id": "aQscOYX87tSq", "status": "running", ...}

# Execute a command (free after sandbox is created)
curl -X POST https://api.sandbank.dev/v1/boxes/aQscOYX87tSq/exec \
  -H "Content-Type: application/json" \
  -d '{"cmd": ["echo", "Hello from the sandbox"]}'

# → {"exit_code": 0, "stdout": "Hello from the sandbox\n", ...}

# Destroy when done (free)
curl -X DELETE https://api.sandbank.dev/v1/boxes/aQscOYX87tSq

import { createProvider } from '@sandbank.dev/core'
import { SandbankCloudAdapter } from '@sandbank.dev/cloud'

const provider = createProvider(
  new SandbankCloudAdapter({
    // x402: pay $0.02/sandbox with USDC on Base
    walletPrivateKey: process.env.WALLET_PRIVATE_KEY,

    // Or use API token (bypasses x402 payment)
    // apiToken: process.env.SANDBANK_API_TOKEN,
  })
)

const sandbox = await provider.create({
  image: 'codebox',
  resources: { cpu: 2, memory: 1024 },
  ports: [[0, 7681], [0, 8080]],
})

const { stdout } = await sandbox.exec('node -e "console.log(42)"')
console.log(stdout) // 42

await provider.destroy(sandbox.id)

ADMIN_BOX_LIFECYCLE_WEBHOOK_URL=https://ops.example.com/webhooks/sandbank
ADMIN_BOX_LIFECYCLE_WEBHOOK_TOKEN=change-me
ADMIN_BOX_LIFECYCLE_WEBHOOK_TIMEOUT_MS=2000

# Tenant ids must match box user_id values.
# For API keys, user_id is the AGENT_API_KEYS label: wanman:key
TENANT_BOX_LIFECYCLE_WEBHOOKS='{
  "wanman": {
    "url": "https://wanman.example.com/webhooks/sandbank",
    "secret": "wanman-hmac-secret",
    "token": "optional-bearer-token",
    "events": ["box.error", "box.terminated"],
    "timeout_ms": 1500
  }
}'
TENANT_BOX_LIFECYCLE_WEBHOOK_TIMEOUT_MS=2000

{
  "event": "box.error",
  "audience": "tenant",
  "tenant_id": "wanman",
  "box_id": "box-1",
  "image": "codebox",
  "previous_status": "running",
  "status": "error",
  "reason": "probe_failure",
  "observed_at": "2026-05-01T05:41:00.000Z"
}

# Create sandbox with port forwarding
curl -X POST https://api.sandbank.dev/v1/boxes \
  -H "Content-Type: application/json" \
  -d '{"image": "codebox", "ports": [[0, 8080], [0, 7681]]}'

# → {"id": "abc", "ports": {"8080": 10042, "7681": 10043}, ...}

# Access guest port 8080 via HTTP proxy
curl https://api.sandbank.dev/v1/boxes/abc/proxy/8080/