Skip to main content
Monitor all processes running in your sandbox, including system processes and background code executions. This helps you track resource usage, debug issues, and manage long-running tasks.

​
Overview

HopX provides two types of process listings:
  • System Processes: All processes running in the sandbox (requires Agent v3.2.0+)
  • Background Executions: Processes started via execute_code_background() or run_code_background()
System process listing requires VM Agent v3.2.0 or later. Check your agent version using sandbox.get_agent_info().

​
System Processes

List all system processes running in the sandbox:
  • Python
  • JavaScript
from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# List all system processes
processes = sandbox.list_system_processes()

print(f"Total Processes: {len(processes)}")
print("\nProcess List:")
for proc in processes[:10]:  # Show first 10
    print(f"PID {proc['pid']}: {proc['command']} (User: {proc['user']})")

sandbox.kill()
Expected Output:
Total Processes: 45

Process List:
PID 1: /sbin/init (User: root)
PID 2: [kthreadd] (User: root)
PID 3: [rcu_gp] (User: root)
PID 4: [rcu_par_gp] (User: root)
PID 5: [kworker/0:0] (User: root)
PID 6: [mm_percpu_wq] (User: root)
PID 7: [ksoftirqd/0] (User: root)
PID 8: [rcu_sched] (User: root)
PID 9: [migration/0] (User: root)
PID 10: [idle_inject/0] (User: root)

​
Background Execution Processes

List processes started via background execution:
  • Python
  • JavaScript
from hopx_ai import Sandbox
import time

sandbox = Sandbox.create(template="code-interpreter")

# Start a background process
process_id = sandbox.run_code_async("""
import time
for i in range(10):
    print(f"Step {i+1}")
    time.sleep(2)
""")

print(f"Started background process: {process_id}")

# Wait a moment
time.sleep(3)

# List background processes
processes = sandbox.list_processes()

print(f"\nBackground Processes: {len(processes)}")
for proc in processes:
    print(f"Process ID: {proc['process_id']}")
    print(f"Status: {proc['status']}")
    if 'stdout' in proc:
        print(f"Output: {proc['stdout'][:100]}...")

sandbox.kill()
Expected Output:
Started background process: proc_abc123xyz

Background Processes: 1
Process ID: proc_abc123xyz
Status: running
Output: Step 1
Step 2
...

​
Process Structure

​
System Process Object

{
  "pid": 1234,
  "name": "python3",
  "command": "/usr/bin/python3 /workspace/script.py",
  "user": "root",
  "cpu_percent": 2.5,
  "memory_mb": 45,
  "status": "running",
  "start_time": "2025-01-27T10:00:00Z"
}

​
Background Process Object

{
  "process_id": "proc_abc123",
  "status": "running",
  "stdout": "Step 1\nStep 2\n",
  "stderr": "",
  "exit_code": null,
  "created_at": "2025-01-27T10:00:00Z"
}

​
Filtering and Searching

Filter processes by command or user:
  • Python
  • JavaScript
from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# List all system processes
all_processes = sandbox.list_system_processes()

# Filter Python processes
python_processes = [
    p for p in all_processes 
    if 'python' in p['command'].lower()
]

print(f"Python Processes: {len(python_processes)}")
for proc in python_processes:
    print(f"PID {proc['pid']}: {proc['command']}")
    print(f"  CPU: {proc.get('cpu_percent', 0):.1f}%, Memory: {proc.get('memory_mb', 0)} MB")

# Filter by user
root_processes = [
    p for p in all_processes 
    if p['user'] == 'root'
]
print(f"\nRoot Processes: {len(root_processes)}")

sandbox.kill()
Expected Output:
Python Processes: 2
PID 1234: /usr/bin/python3 /workspace/script.py
  CPU: 2.5%, Memory: 45 MB
PID 1235: /usr/bin/python3 -m http.server
  CPU: 0.8%, Memory: 32 MB

Root Processes: 42

​
Monitoring Process Status

Monitor background processes to track their progress:
  • Python
  • JavaScript
from hopx_ai import Sandbox
import time

sandbox = Sandbox.create(template="code-interpreter")

# Start long-running background process
process_id = sandbox.run_code_async("""
import time
for i in range(5):
    print(f"Processing item {i+1}/5")
    time.sleep(3)
print("Complete!")
""")

print(f"Started process: {process_id}")

# Monitor until complete
while True:
    processes = sandbox.list_processes()
    proc = next((p for p in processes if p['process_id'] == process_id), None)
    
    if not proc:
        print("Process not found")
        break
    
    print(f"Status: {proc['status']}")
    
    if proc['status'] == 'completed':
        print(f"Exit Code: {proc.get('exit_code', 'N/A')}")
        if 'stdout' in proc:
            print(f"Output:\n{proc['stdout']}")
        break
    elif proc['status'] == 'failed':
        print(f"Error: {proc.get('stderr', 'Unknown error')}")
        break
    
    time.sleep(2)

sandbox.kill()
Expected Output:
Started process: proc_abc123xyz
Status: running
Status: running
Status: completed
Exit Code: 0
Output:
Processing item 1/5
Processing item 2/5
Processing item 3/5
Processing item 4/5
Processing item 5/5
Complete!

​
Process Limits

Control the number of processes returned:
  • Python
  • JavaScript
from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# List system processes with limit
# Note: list_system_processes() doesn't support max_results parameter
# The API defaults to 200 processes
processes = sandbox.list_system_processes()

print(f"Returned {len(processes)} processes")
if len(processes) >= 200:
    print("Note: Results may be truncated (max 200)")

sandbox.kill()
Expected Output:
Returned 45 processes

​
Use Cases

​
Debugging Hanging Processes

Identify processes that might be causing issues:
  • Python
  • JavaScript
from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# List all processes
processes = sandbox.list_system_processes()

# Find processes consuming resources
print("All Running Processes:")
for proc in processes:
    print(f"PID {proc['pid']}: {proc['command']}")
    print(f"  CPU: {proc.get('cpu_percent', 0):.1f}%, Memory: {proc.get('memory_mb', 0)} MB, Status: {proc.get('status', 'N/A')}")

# Check for specific problematic processes
zombie_processes = [p for p in processes if 'defunct' in p['command']]
if zombie_processes:
    print(f"\nFound {len(zombie_processes)} zombie processes")

sandbox.kill()
Expected Output:
All Running Processes:
PID 1: /sbin/init
  CPU: 0.0%, Memory: 0 MB, Status: running
PID 2: [kthreadd]
  CPU: 0.0%, Memory: 0 MB, Status: running
...

​
Tracking Background Jobs

Monitor multiple background executions:
  • Python
  • JavaScript
from hopx_ai import Sandbox
import time

sandbox = Sandbox.create(template="code-interpreter")

# Start multiple background processes
process_ids = []
for i in range(3):
    pid = sandbox.run_code_async(f"""
import time
print("Task {i+1} starting")
time.sleep(5)
print("Task {i+1} complete")
""")
    process_ids.append(pid)
    print(f"Started task {i+1}: {pid}")

# Monitor all processes
time.sleep(2)
processes = sandbox.list_processes()

print(f"\nActive Background Processes: {len(processes)}")
for proc in processes:
    if proc['process_id'] in process_ids:
        print(f"  {proc['process_id']}: {proc['status']}")

sandbox.kill()
Expected Output:
Started task 1: proc_task1_xyz
Started task 2: proc_task2_abc
Started task 3: proc_task3_def

Active Background Processes: 3
  proc_task1_xyz: running
  proc_task2_abc: running
  proc_task3_def: running

​
Best Practices

Use system processes to debug issues and understand what’s running in your sandbox environment.
Use background process listing to monitor and manage long-running code executions started via run_code_async() or execute_code_background().
System process listing is limited to 200 processes by default. If you have more processes, results may be truncated.
Check process status regularly for background executions to detect completion or failures early.

​
API Reference

​
Python SDK

  • sandbox.list_system_processes() - List all system processes (v3.2.0+)
  • sandbox.list_processes() - List background execution processes

​
JavaScript SDK

  • sandbox.listSystemProcesses() - List all system processes (v3.2.0+)
  • sandbox.listProcesses() - List background execution processes

​
API Endpoints

  • GET /processes - List all system processes (max 200, v3.2.0+)
  • GET /execute/processes - List background execution processes

​
Next Steps