System

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

hopx system <subcommand> [options]

Subcommands

`health`

Check API health status. Syntax:

hopx system health [OPTIONS]

Examples:

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

hopx system metrics SANDBOX_ID [OPTIONS]

Arguments:

SANDBOX_ID - Sandbox ID (required)

Options:

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

Examples:

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

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:

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

hopx system processes SANDBOX_ID [OPTIONS]

Arguments:

SANDBOX_ID - Sandbox ID (required)

Options:

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

Examples:

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

hopx system jupyter SANDBOX_ID [OPTIONS]

Arguments:

SANDBOX_ID - Sandbox ID (required)

Options:

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

Examples:

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

hopx system snapshot SANDBOX_ID [OPTIONS]

Arguments:

SANDBOX_ID - Sandbox ID (required)

Options:

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

Examples:

# 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

#!/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

#!/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

CLI Quickstart - Get started with CLI
Sandbox Commands - Create and manage sandboxes
Python SDK: Observability - Python SDK system monitoring
JavaScript SDK: Observability - JavaScript SDK system monitoring
API: System Metrics - REST API endpoints

Next Steps

Learn about Sandbox Management to create sandboxes
Explore Observability for monitoring concepts
Review Process Management for process monitoring

Getting Started

Setup

Commands

Command Syntax

Subcommands

`health`

`metrics`

`agent-info`

`processes`

`jupyter`

`snapshot`

Shell Scripting Examples

Monitor Sandbox Health

Check Resource Usage

Next Steps

​Command Syntax

​Subcommands

​health

​metrics

​agent-info

​processes

​jupyter

​snapshot

​Shell Scripting Examples

​Monitor Sandbox Health

​Check Resource Usage

​Related

​Next Steps

Command Syntax

Subcommands

`health`

`metrics`

`agent-info`

`processes`

`jupyter`

`snapshot`

Shell Scripting Examples

Monitor Sandbox Health

Check Resource Usage

Related

Next Steps