> ## 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.

# System

> Complete reference for HopX CLI system commands - health checks, metrics, agent info, processes, Jupyter access, and system snapshots. Monitor and inspect sandbox system resources.

Monitor and inspect HopX sandbox system resources using the `system` command. Check health, view metrics, get agent information, list processes, access Jupyter, and capture system snapshots.

## Command Syntax

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

## Subcommands

### `health`

Check API health status.

**Syntax:**

```bash theme={null}
hopx system health [OPTIONS]
```

**Examples:**

```bash theme={null}
# Check API health
hopx system health
```

**Expected Output:**

```
✓ API is healthy
✓ All services operational
```

**Exit Codes:**

* `0` - Healthy
* `1` - Unhealthy
* `6` - Network error

### `metrics`

Get sandbox system metrics.

**Syntax:**

```bash theme={null}
hopx system metrics SANDBOX_ID [OPTIONS]
```

**Arguments:**

* `SANDBOX_ID` - Sandbox ID (required)

**Options:**

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

**Examples:**

```bash theme={null}
# Get sandbox metrics
hopx system metrics sb_abc123

# Get metrics with JSON output
hopx system metrics sb_abc123 --output json
```

**Expected Output (Table):**

```
┌─────────────┬─────────────────────────────────────┐
│ Metric      │ Value                               │
├─────────────┼─────────────────────────────────────┤
│ CPU Usage   │ 15.2%                               │
│ Memory      │ 512 MB / 2 GB (25.6%)              │
│ Disk Usage  │ 1.2 GB / 10 GB (12.0%)              │
│ Uptime      │ 2h 15m                              │
└─────────────┴─────────────────────────────────────┘
```

**Exit Codes:**

* `0` - Success
* `3` - Authentication error
* `4` - Sandbox not found

### `agent-info`

Get VM agent information.

**Syntax:**

```bash theme={null}
hopx system agent-info SANDBOX_ID [OPTIONS]
```

**Arguments:**

* `SANDBOX_ID` - Sandbox ID (required)

**Options:**

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

**Examples:**

```bash theme={null}
# Get agent info
hopx system agent-info sb_abc123

# Get info with JSON output
hopx system agent-info sb_abc123 --output json
```

**Expected Output (Table):**

```
┌─────────────┬─────────────────────────────────────┐
│ Property    │ Value                               │
├─────────────┼─────────────────────────────────────┤
│ Version     │ 1.2.3                               │
│ Status      │ running                             │
│ Features    │ code-execution, files, terminal      │
└─────────────┴─────────────────────────────────────┘
```

**Exit Codes:**

* `0` - Success
* `3` - Authentication error
* `4` - Sandbox not found

### `processes`

List running processes in a sandbox.

**Syntax:**

```bash theme={null}
hopx system processes SANDBOX_ID [OPTIONS]
```

**Arguments:**

* `SANDBOX_ID` - Sandbox ID (required)

**Options:**

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

**Examples:**

```bash theme={null}
# List processes
hopx system processes sb_abc123

# List with JSON output
hopx system processes sb_abc123 --output json
```

**Expected Output (Table):**

```
┌──────┬──────────────┬─────────┬─────────────┐
│ PID  │ Command      │ User    │ CPU %      │
├──────┼──────────────┼─────────┼─────────────┤
│ 1234 │ python       │ user    │ 5.2        │
│ 1235 │ node         │ user    │ 2.1        │
└──────┴──────────────┴─────────┴─────────────┘
```

**Exit Codes:**

* `0` - Success
* `3` - Authentication error
* `4` - Sandbox not found

### `jupyter`

Get Jupyter access information.

**Syntax:**

```bash theme={null}
hopx system jupyter SANDBOX_ID [OPTIONS]
```

**Arguments:**

* `SANDBOX_ID` - Sandbox ID (required)

**Options:**

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

**Examples:**

```bash theme={null}
# Get Jupyter info
hopx system jupyter sb_abc123
```

**Expected Output:**

```
Jupyter URL: https://jupyter-sb_abc123.us-east.vms.hopx.dev/
Token: jupyter-token-abc123
```

**Exit Codes:**

* `0` - Success
* `3` - Authentication error
* `4` - Sandbox not found

### `snapshot`

Capture system snapshot.

**Syntax:**

```bash theme={null}
hopx system snapshot SANDBOX_ID [OPTIONS]
```

**Arguments:**

* `SANDBOX_ID` - Sandbox ID (required)

**Options:**

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

**Examples:**

```bash theme={null}
# Capture system snapshot
hopx system snapshot sb_abc123
```

**Expected Output:**

```
✓ System snapshot captured
✓ Snapshot ID: snap_abc123
```

**Exit Codes:**

* `0` - Success
* `3` - Authentication error
* `4` - Sandbox not found

## Shell Scripting Examples

### Monitor Sandbox Health

```bash theme={null}
#!/bin/bash

# Check API health
if ! hopx system health > /dev/null 2>&1; then
    echo "API is unhealthy"
    exit 1
fi

# Monitor sandbox metrics
hopx system metrics sb_abc123 --output json | jq '.cpu_percent'
```

### Check Resource Usage

```bash theme={null}
#!/bin/bash

# Get metrics and check memory usage
MEMORY=$(hopx system metrics sb_abc123 --output json | jq -r '.memory_percent')

if (( $(echo "$MEMORY > 80" | bc -l) )); then
    echo "Warning: High memory usage: ${MEMORY}%"
fi
```

## Related

* **[CLI Quickstart](/cli/quickstart)** - Get started with CLI
* **[Sandbox Commands](/cli/commands/sandbox)** - Create and manage sandboxes
* **[Python SDK: Observability](/sdk/python/observability)** - Python SDK system monitoring
* **[JavaScript SDK: Observability](/sdk/javascript/observability)** - JavaScript SDK system monitoring
* **[API: System Metrics](/api/vm-agent/get-system-metrics)** - REST API endpoints

## Next Steps

* Learn about [Sandbox Management](/cli/commands/sandbox) to create sandboxes
* Explore [Observability](/core-concepts/observability/metrics) for monitoring concepts
* Review [Process Management](/core-concepts/observability/processes) for process monitoring