Process Monitoring

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)

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({
  template: 'code-interpreter'
});

// List all system processes
const processes = await sandbox.listSystemProcesses();

console.log(`Total Processes: ${processes.length}`);
console.log('\nProcess List:');
for (const proc of processes.slice(0, 10)) {  // Show first 10
  console.log(`PID ${proc.pid}: ${proc.command} (User: ${proc.user})`);
}

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

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({
  template: 'code-interpreter'
});

// Start a background process
const processId = await sandbox.runCodeAsync(`
import time
for i in range(10):
    print(f"Step {i+1}")
    time.sleep(2)
`);

console.log(`Started background process: ${processId}`);

// Wait a moment
await new Promise(resolve => setTimeout(resolve, 3000));

// List background processes
const processes = await sandbox.listProcesses();

console.log(`\nBackground Processes: ${processes.length}`);
for (const proc of processes) {
  console.log(`Process ID: ${proc.process_id}`);
  console.log(`Status: ${proc.status}`);
  if (proc.stdout) {
    console.log(`Output: ${proc.stdout.substring(0, 100)}...`);
  }
}

await 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

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({
  template: 'code-interpreter'
});

// List all system processes
const allProcesses = await sandbox.listSystemProcesses();

// Filter Python processes
const pythonProcesses = allProcesses.filter(
  p => p.command.toLowerCase().includes('python')
);

console.log(`Python Processes: ${pythonProcesses.length}`);
for (const proc of pythonProcesses) {
  console.log(`PID ${proc.pid}: ${proc.command}`);
  console.log(`  CPU: ${(proc.cpu_percent || 0).toFixed(1)}%, Memory: ${proc.memory_mb || 0} MB`);
}

// Filter by user
const rootProcesses = allProcesses.filter(
  p => p.user === 'root'
);
console.log(`\nRoot Processes: ${rootProcesses.length}`);

await 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!

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({
  template: 'code-interpreter'
});

// Start long-running background process
const processId = await sandbox.runCodeAsync(`
import time
for i in range(5):
    print(f"Processing item {i+1}/5")
    time.sleep(3)
print("Complete!")
`);

console.log(`Started process: ${processId}`);

// Monitor until complete
while (true) {
  const processes = await sandbox.listProcesses();
  const proc = processes.find(p => p.process_id === processId);
  
  if (!proc) {
    console.log('Process not found');
    break;
  }
  
  console.log(`Status: ${proc.status}`);
  
  if (proc.status === 'completed') {
    console.log(`Exit Code: ${proc.exit_code || 'N/A'}`);
    if (proc.stdout) {
      console.log(`Output:\n${proc.stdout}`);
    }
    break;
  } else if (proc.status === 'failed') {
    console.log(`Error: ${proc.stderr || 'Unknown error'}`);
    break;
  }
  
  await new Promise(resolve => setTimeout(resolve, 2000));
}

await 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

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({
  template: 'code-interpreter'
});

// List system processes
// Note: listSystemProcesses() doesn't support maxResults parameter
// The API defaults to 200 processes
const processes = await sandbox.listSystemProcesses();

console.log(`Returned ${processes.length} processes`);
if (processes.length >= 200) {
  console.log('Note: Results may be truncated (max 200)');
}

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

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({
  template: 'code-interpreter'
});

// List all processes
const processes = await sandbox.listSystemProcesses();

// Find processes consuming resources
console.log('All Running Processes:');
for (const proc of processes) {
  console.log(`PID ${proc.pid}: ${proc.command}`);
  console.log(`  CPU: ${(proc.cpu_percent || 0).toFixed(1)}%, Memory: ${proc.memory_mb || 0} MB, Status: ${proc.status || 'N/A'}`);
}

// Check for specific problematic processes
const zombieProcesses = processes.filter(
  p => p.command.includes('defunct')
);
if (zombieProcesses.length > 0) {
  console.log(`\nFound ${zombieProcesses.length} zombie processes`);
}

await 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

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({
  template: 'code-interpreter'
});

// Start multiple background processes
const processIds = [];
for (let i = 0; i < 3; i++) {
  const pid = await sandbox.runCodeAsync(`
import time
print("Task ${i+1} starting")
time.sleep(5)
print("Task ${i+1} complete")
`);
  processIds.push(pid);
  console.log(`Started task ${i+1}: ${pid}`);
}

// Monitor all processes
await new Promise(resolve => setTimeout(resolve, 2000));
const processes = await sandbox.listProcesses();

console.log(`\nActive Background Processes: ${processes.length}`);
for (const proc of processes) {
  if (processIds.includes(proc.process_id)) {
    console.log(`  ${proc.process_id}: ${proc.status}`);
  }
}

await 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

System Metrics - Monitor agent performance metrics
Background Execution - Start background processes
SDK: sandbox.list_processes() - Python SDK method
API: GET /execute/processes - VM Agent API endpoint
CLI System Commands - System operations from CLI

Next Steps

Learn about System Metrics to monitor agent performance
Explore Background Execution to start background processes
Review Process Management for advanced process control

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Overview

System Processes

Background Execution Processes

Process Structure

System Process Object

Background Process Object

Filtering and Searching

Monitoring Process Status

Process Limits

Use Cases

Debugging Hanging Processes

Tracking Background Jobs

Best Practices

API Reference

Python SDK

JavaScript SDK

API Endpoints

Next Steps

​Overview

​System Processes

​Background Execution Processes

​Process Structure

​System Process Object

​Background Process Object

​Filtering and Searching

​Monitoring Process Status

​Process Limits

​Use Cases

​Debugging Hanging Processes

​Tracking Background Jobs

​Best Practices

​API Reference

​Python SDK

​JavaScript SDK

​API Endpoints

​Related

​Next Steps

Overview

System Processes

Background Execution Processes

Process Structure

System Process Object

Background Process Object

Filtering and Searching

Monitoring Process Status

Process Limits

Use Cases

Debugging Hanging Processes

Tracking Background Jobs

Best Practices

API Reference

Python SDK

JavaScript SDK

API Endpoints

Related

Next Steps