Skip to main content
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

​
Next Steps