Skip to main content
Manage sandbox lifecycle with the sandbox command (alias: sb). Create, list, pause, resume, and kill sandboxes from the command line.

​
Command Syntax

hopx sandbox <subcommand> [options]

​
Subcommands

​
create

Create a new sandbox from a template. Syntax: 
hopx sandbox create [OPTIONS]
Options:
  • --template, -t TEXT - Template name or ID (default: code-interpreter)
  • --template-id TEXT - Template ID (alternative to --template)
  • --timeout INTEGER - Auto-kill timeout in seconds (0 = no timeout)
  • --region TEXT - Preferred deployment region (e.g., us-east, eu-west)
  • --env TEXT - Environment variable in KEY=VALUE format (repeatable)
  • --env-file PATH - Load environment variables from file
  • --no-internet - Disable internet access for sandbox
  • --output, -o FORMAT - Output format: table, json, plain (default: table)
Examples: 
# Create sandbox with Python template
hopx sandbox create --template python

# Create with timeout
hopx sandbox create --template python --timeout 7200

# Create in specific region
hopx sandbox create --template python --region us-east

# Get JSON output for scripting
hopx sandbox create --template python --output json
Expected Output (Table): 
┌──────────────────┬─────────┬────────────┐
│ ID               │ Status  │ Template   │
├──────────────────┼─────────┼────────────┤
│ sb_abc123        │ running │ python     │
└──────────────────┴─────────┴────────────┘
Expected Output (JSON): 
{
  "id": "sb_abc123",
  "status": "running",
  "template": "python",
  "created_at": "2025-01-27T10:00:00Z"
}
Exit Codes:
  • 0 - Success
  • 3 - Authentication error
  • 4 - Template not found
  • 7 - Rate limit exceeded

​
list

List all sandboxes. Syntax: 
hopx sandbox list [OPTIONS]
Options:
  • --status TEXT - Filter by status: running, paused, stopped
  • --template TEXT - Filter by template
  • --output, -o FORMAT - Output format: table, json, plain (default: table)
Examples: 
# List all sandboxes
hopx sandbox list

# List running sandboxes only
hopx sandbox list --status running

# List with JSON output
hopx sandbox list --output json

# Filter by template
hopx sandbox list --template python
Expected Output (Table): 
┌──────────────────┬─────────┬────────────┬─────────────────────┐
│ ID               │ Status  │ Template   │ Created             │
├──────────────────┼─────────┼────────────┼─────────────────────┤
│ sb_abc123        │ running │ python     │ 2025-01-27 10:00:00 │
│ sb_def456        │ paused  │ nodejs     │ 2025-01-27 09:00:00 │
└──────────────────┴─────────┴────────────┴─────────────────────┘
Exit Codes:
  • 0 - Success
  • 3 - Authentication error

​
info

Get detailed information about a sandbox. Syntax: 
hopx sandbox info SANDBOX_ID [OPTIONS]
Options:
  • --output, -o FORMAT - Output format: table, json, plain (default: table)
Examples: 
# Get sandbox info
hopx sandbox info sb_abc123

# Get JSON output
hopx sandbox info sb_abc123 --output json
Expected Output (Table): 
┌─────────────────┬─────────────────────────────────────┐
│ Field           │ Value                               │
├─────────────────┼─────────────────────────────────────┤
│ ID              │ sb_abc123                           │
│ Status          │ running                             │
│ Template        │ python                              │
│ Region          │ us-east                             │
│ Created         │ 2025-01-27 10:00:00                 │
│ Timeout         │ 3600 seconds                        │
└─────────────────┴─────────────────────────────────────┘
Exit Codes:
  • 0 - Success
  • 3 - Authentication error
  • 4 - Sandbox not found

​
pause

Pause a running sandbox (preserves state, saves resources). Syntax: 
hopx sandbox pause SANDBOX_ID [OPTIONS]
Options:
  • --force - Skip confirmation prompt
Examples: 
# Pause sandbox
hopx sandbox pause sb_abc123

# Pause without confirmation
hopx sandbox pause sb_abc123 --force
Expected Output: 
✓ Sandbox paused: sb_abc123
Exit Codes:
  • 0 - Success
  • 3 - Authentication error
  • 4 - Sandbox not found

​
resume

Resume a paused sandbox. Syntax: 
hopx sandbox resume SANDBOX_ID [OPTIONS]
Examples: 
# Resume sandbox
hopx sandbox resume sb_abc123
Expected Output: 
✓ Sandbox resumed: sb_abc123
Exit Codes:
  • 0 - Success
  • 3 - Authentication error
  • 4 - Sandbox not found

​
kill

Kill a sandbox (permanently delete). Syntax: 
hopx sandbox kill SANDBOX_ID [OPTIONS]
Options:
  • --force - Skip confirmation prompt
Examples: 
# Kill sandbox (with confirmation)
hopx sandbox kill sb_abc123

# Kill without confirmation
hopx sandbox kill sb_abc123 --force
Expected Output: 
✓ Sandbox killed: sb_abc123
Exit Codes:
  • 0 - Success
  • 3 - Authentication error
  • 4 - Sandbox not found

​
url

Get preview URL for a service running on a port. Syntax: 
hopx sandbox url SANDBOX_ID --port PORT [OPTIONS]
Options:
  • --port INTEGER - Port number (required)
Examples: 
# Get preview URL for port 8080
hopx sandbox url sb_abc123 --port 8080
Expected Output: 
https://8080-sb_abc123.us-east.vms.hopx.dev/
Exit Codes:
  • 0 - Success
  • 3 - Authentication error
  • 4 - Sandbox not found

​
Shell Scripting Examples

​
Create and Use Sandbox

#!/bin/bash
set -e

# Create sandbox
SANDBOX_ID=$(hopx sandbox create --template python --output json | jq -r '.id')
echo "Created sandbox: $SANDBOX_ID"

# Use sandbox
hopx run "print('Hello')" --sandbox "$SANDBOX_ID"

# Cleanup
trap "hopx sandbox kill $SANDBOX_ID --force" EXIT

​
List and Process Sandboxes

#!/bin/bash

# List running sandboxes
hopx sandbox list --status running --output json | jq -r '.[].id' | while read id; do
    echo "Processing sandbox: $id"
    hopx sandbox info "$id"
done

​
Conditional Sandbox Management

#!/bin/bash

# Create sandbox with error handling
if SANDBOX_ID=$(hopx sandbox create --template python --output json 2>/dev/null | jq -r '.id'); then
    echo "Sandbox created: $SANDBOX_ID"
else
    case $? in
        3) echo "Authentication failed" ;;
        4) echo "Template not found" ;;
        7) echo "Rate limit exceeded" ;;
        *) echo "Error creating sandbox" ;;
    esac
    exit 1
fi

​
Next Steps