> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Complete reference for HopX CLI sandbox commands - create, list, pause, resume, kill, and manage sandboxes. Includes all flags, options, examples, and exit codes for sandbox lifecycle management.

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

## Command Syntax

```bash theme={null}
hopx sandbox <subcommand> [options]
```

## Subcommands

### `create`

Create a new sandbox from a template.

**Syntax:**

```bash theme={null}
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:**

```bash theme={null}
# 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):**

```json theme={null}
{
  "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:**

```bash theme={null}
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:**

```bash theme={null}
# 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:**

```bash theme={null}
hopx sandbox info SANDBOX_ID [OPTIONS]
```

**Options:**

* `--output, -o FORMAT` - Output format: `table`, `json`, `plain` (default: `table`)

**Examples:**

```bash theme={null}
# 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:**

```bash theme={null}
hopx sandbox pause SANDBOX_ID [OPTIONS]
```

**Options:**

* `--force` - Skip confirmation prompt

**Examples:**

```bash theme={null}
# 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:**

```bash theme={null}
hopx sandbox resume SANDBOX_ID [OPTIONS]
```

**Examples:**

```bash theme={null}
# 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:**

```bash theme={null}
hopx sandbox kill SANDBOX_ID [OPTIONS]
```

**Options:**

* `--force` - Skip confirmation prompt

**Examples:**

```bash theme={null}
# 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:**

```bash theme={null}
hopx sandbox url SANDBOX_ID --port PORT [OPTIONS]
```

**Options:**

* `--port INTEGER` - Port number (required)

**Examples:**

```bash theme={null}
# 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

```bash theme={null}
#!/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

```bash theme={null}
#!/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

```bash theme={null}
#!/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
```

## Related

* **[CLI Quickstart](/cli/quickstart)** - Get started with CLI
* **[Code Execution](/cli/commands/run)** - Execute code in sandboxes
* **[File Operations](/cli/commands/files)** - Manage files in sandboxes
* **[Python SDK: Sandbox](/sdk/python/sandbox)** - Python SDK sandbox methods
* **[JavaScript SDK: Sandbox](/sdk/javascript/sandbox)** - JavaScript SDK sandbox methods
* **[API: Create Sandbox](/api/control-plane/create-sandbox)** - REST API endpoint

## Next Steps

* Learn about [Code Execution](/cli/commands/run) to execute code in sandboxes
* Explore [File Operations](/cli/commands/files) to manage files
* Review [Templates](/cli/commands/template) to list and build custom templates