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

# Process Monitoring

> List and monitor system processes and background executions in HopX sandboxes. Track running processes, monitor background code execution, check process status, and manage process lifecycle. Essential for debugging, performance monitoring, and resource management. Includes Python and JavaScript SDK examples and REST API endpoints.

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()`

<Note>
  System process listing requires VM Agent v3.2.0 or later. Check your agent version using `sandbox.get_agent_info()`.
</Note>

## System Processes

List all system processes running in the sandbox:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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)
    ```
  </Tab>
</Tabs>

## Background Execution Processes

List processes started via background execution:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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
    ...
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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
    ...
    ```
  </Tab>
</Tabs>

## Process Structure

### System Process Object

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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
    ```
  </Tab>
</Tabs>

## Monitoring Process Status

Monitor background processes to track their progress:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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!
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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!
    ```
  </Tab>
</Tabs>

## Process Limits

Control the number of processes returned:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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
    ```
  </Tab>
</Tabs>

## Use Cases

### Debugging Hanging Processes

Identify processes that might be causing issues:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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
    ...
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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
    ...
    ```
  </Tab>
</Tabs>

### Tracking Background Jobs

Monitor multiple background executions:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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
    ```
  </Tab>
</Tabs>

## Best Practices

<Tip>
  **Use system processes** to debug issues and understand what's running in your sandbox environment.
</Tip>

<Tip>
  **Use background process listing** to monitor and manage long-running code executions started via `run_code_async()` or `execute_code_background()`.
</Tip>

<Warning>
  **System process listing is limited to 200 processes** by default. If you have more processes, results may be truncated.
</Warning>

<Tip>
  **Check process status regularly** for background executions to detect completion or failures early.
</Tip>

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

## Related

* **[System Metrics](/core-concepts/observability/metrics)** - Monitor agent performance metrics
* **[Background Execution](/core-concepts/code-execution/background)** - Start background processes
* **SDK**: [sandbox.list\_processes()](/sdk/python/sandbox#list_processes) - Python SDK method
* **API**: [GET /execute/processes](/api/vm-agent/list-processes) - VM Agent API endpoint
* [CLI System Commands](/cli/commands/system) - System operations from CLI

## Next Steps

* Learn about [System Metrics](/core-concepts/observability/metrics) to monitor agent performance
* Explore [Background Execution](/core-concepts/code-execution/background) to start background processes
* Review [Process Management](/core-concepts/code-execution/process-management) for advanced process control