Skip to main content

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.

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