Sandbox

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

CLI Quickstart - Get started with CLI
Code Execution - Execute code in sandboxes
File Operations - Manage files in sandboxes
Python SDK: Sandbox - Python SDK sandbox methods
JavaScript SDK: Sandbox - JavaScript SDK sandbox methods
API: Create Sandbox - REST API endpoint

Next Steps

Learn about Code Execution to execute code in sandboxes
Explore File Operations to manage files
Review Templates to list and build custom templates

Getting Started

Setup

Commands

Command Syntax

Subcommands

`create`

`list`

`info`

`pause`

`resume`

`kill`

`url`

Shell Scripting Examples

Create and Use Sandbox

List and Process Sandboxes

Conditional Sandbox Management

Next Steps

​Command Syntax

​Subcommands

​create

​list

​info

​pause

​resume

​kill

​url

​Shell Scripting Examples

​Create and Use Sandbox

​List and Process Sandboxes

​Conditional Sandbox Management

​Related

​Next Steps

Command Syntax

Subcommands

`create`

`list`

`info`

`pause`

`resume`

`kill`

`url`

Shell Scripting Examples

Create and Use Sandbox

List and Process Sandboxes

Conditional Sandbox Management

Related

Next Steps