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

> List, monitor, and manage background execution processes in HopX sandboxes. Track running processes, check execution status, terminate stuck processes, and manage process lifecycle. Essential for managing long-running code execution and debugging. Includes Python and JavaScript SDK examples and REST API endpoints.

Process management allows you to monitor and control background execution processes. You can list running processes, check their status, and terminate them when needed.

## Overview

Process management is essential for:

* Monitoring background execution progress
* Checking process status and output
* Terminating long-running or stuck processes
* Managing multiple concurrent executions

<Note>
  Process management works with processes started via `run_code_background()`. For system processes, see system process listing in the Observability section.
</Note>

## Listing Processes

List all background execution processes:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

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

    # List all processes
    processes = sandbox.list_processes()

    print(f"Found {len(processes)} processes")
    for proc in processes:
        print(f"  {proc.get('name', 'unnamed')}: {proc['status']} (ID: {proc['process_id']})")

    sandbox.kill()
    ```
  </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.listProcesses();

    console.log(`Found ${processes.length} processes`);
    for (const proc of processes) {
      console.log(`  ${proc.name || 'unnamed'}: ${proc.status} (ID: ${proc.processId})`);
    }

    await sandbox.kill();
    ```
  </Tab>
</Tabs>

## Process Status

Check detailed status of processes:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

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

    # Start a background process
    result = sandbox.run_code_background(
        code='import time; time.sleep(30)',
        language='python',
        name='status-demo'
    )

    process_id = result['process_id']

    # Check status
    processes = sandbox.list_processes()
    proc = next((p for p in processes if p['process_id'] == process_id), None)

    if proc:
        print(f"Process: {proc.get('name', 'unnamed')}")
        print(f"Status: {proc['status']}")
        print(f"Process ID: {proc['process_id']}")
        print(f"Execution ID: {proc.get('execution_id', 'N/A')}")
        
        if proc['status'] == 'completed':
            print(f"Output: {proc.get('stdout', '')}")
        elif proc['status'] == 'failed':
            print(f"Error: {proc.get('stderr', '')}")

    sandbox.kill()
    ```
  </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 result = await sandbox.runCodeBackground(
      'import time; time.sleep(30)',
      {
        language: 'python',
        name: 'status-demo'
      }
    );

    const processId = result.processId;

    // Check status
    const processes = await sandbox.listProcesses();
    const proc = processes.find(p => p.processId === processId);

    if (proc) {
      console.log(`Process: ${proc.name || 'unnamed'}`);
      console.log(`Status: ${proc.status}`);
      console.log(`Process ID: ${proc.processId}`);
      console.log(`Execution ID: ${proc.executionId || 'N/A'}`);
      
      if (proc.status === 'completed') {
        console.log(`Output: ${proc.stdout || ''}`);
      } else if (proc.status === 'failed') {
        console.log(`Error: ${proc.stderr || ''}`);
      }
    }

    await sandbox.kill();
    ```
  </Tab>
</Tabs>

## Process States

Processes can be in different states:

* **`queued`** - Waiting to start
* **`running`** - Currently executing
* **`completed`** - Finished successfully
* **`failed`** - Execution failed
* **`killed`** - Terminated by user

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

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

    # Start multiple processes
    proc1 = sandbox.run_code_background('import time; time.sleep(10)', name='task-1')
    proc2 = sandbox.run_code_background('import time; time.sleep(20)', name='task-2')

    # Check states
    processes = sandbox.list_processes()
    for proc in processes:
        status = proc['status']
        name = proc.get('name', 'unnamed')
        
        if status == 'running':
            print(f"🟢 {name} is running")
        elif status == 'completed':
            print(f"✅ {name} completed")
        elif status == 'failed':
            print(f"❌ {name} failed")
        elif status == 'queued':
            print(f"⏳ {name} is queued")
        elif status == 'killed':
            print(f"🛑 {name} was killed")

    sandbox.kill()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

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

    // Start multiple processes
    const proc1 = await sandbox.runCodeBackground('import time; time.sleep(10)', { name: 'task-1' });
    const proc2 = await sandbox.runCodeBackground('import time; time.sleep(20)', { name: 'task-2' });

    // Check states
    const processes = await sandbox.listProcesses();
    for (const proc of processes) {
      const status = proc.status;
      const name = proc.name || 'unnamed';
      
      if (status === 'running') {
        console.log(`🟢 ${name} is running`);
      } else if (status === 'completed') {
        console.log(`✅ ${name} completed`);
      } else if (status === 'failed') {
        console.log(`❌ ${name} failed`);
      } else if (status === 'queued') {
        console.log(`⏳ ${name} is queued`);
      } else if (status === 'killed') {
        console.log(`🛑 ${name} was killed`);
      }
    }

    await sandbox.kill();
    ```
  </Tab>
</Tabs>

## Killing Processes

Terminate running processes:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

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

    # Start a long-running process
    result = sandbox.run_code_background(
        code='import time; time.sleep(300)',
        language='python',
        name='long-task'
    )

    process_id = result['process_id']
    print(f"Started process: {process_id}")

    # Kill the process
    sandbox.kill_process(process_id)
    print("Process killed")

    # Verify it's killed
    processes = sandbox.list_processes()
    proc = next((p for p in processes if p['process_id'] == process_id), None)
    if proc:
        print(f"Status: {proc['status']}")  # Should be 'killed'

    sandbox.kill()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

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

    // Start a long-running process
    const result = await sandbox.runCodeBackground(
      'import time; time.sleep(300)',
      {
        language: 'python',
        name: 'long-task'
      }
    );

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

    // Kill the process
    await sandbox.killProcess(processId);
    console.log('Process killed');

    // Verify it's killed
    const processes = await sandbox.listProcesses();
    const proc = processes.find(p => p.processId === processId);
    if (proc) {
      console.log(`Status: ${proc.status}`);  // Should be 'killed'
    }

    await sandbox.kill();
    ```
  </Tab>
</Tabs>

## Monitoring Multiple Processes

Monitor multiple processes simultaneously:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox
    import time

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

    # Start multiple processes
    processes = []
    for i in range(3):
        result = sandbox.run_code_background(
            code=f'import time; time.sleep({10 + i*5})',
            language='python',
            name=f'task-{i+1}'
        )
        processes.append(result['process_id'])

    print(f"Started {len(processes)} processes")

    # Monitor all processes
    while True:
        all_processes = sandbox.list_processes()
        active = [p for p in all_processes if p['process_id'] in processes and p['status'] in ['queued', 'running']]
        
        if not active:
            print("All processes completed")
            break
        
        print(f"\nActive processes: {len(active)}")
        for proc in active:
            print(f"  {proc.get('name')}: {proc['status']}")
        
        time.sleep(2)

    # Show final status
    all_processes = sandbox.list_processes()
    for proc in all_processes:
        if proc['process_id'] in processes:
            print(f"{proc.get('name')}: {proc['status']}")

    sandbox.kill()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

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

    // Start multiple processes
    const processIds = [];
    for (let i = 0; i < 3; i++) {
      const result = await sandbox.runCodeBackground(
        `import time; time.sleep(${10 + i * 5})`,
        {
          language: 'python',
          name: `task-${i + 1}`
        }
      );
      processIds.push(result.processId);
    }

    console.log(`Started ${processIds.length} processes`);

    // Monitor all processes
    while (true) {
      const allProcesses = await sandbox.listProcesses();
      const active = allProcesses.filter(
        p => processIds.includes(p.processId) && 
        ['queued', 'running'].includes(p.status)
      );
      
      if (active.length === 0) {
        console.log('All processes completed');
        break;
      }
      
      console.log(`\nActive processes: ${active.length}`);
      for (const proc of active) {
        console.log(`  ${proc.name}: ${proc.status}`);
      }
      
      await new Promise(resolve => setTimeout(resolve, 2000));
    }

    // Show final status
    const finalProcesses = await sandbox.listProcesses();
    for (const proc of finalProcesses) {
      if (processIds.includes(proc.processId)) {
        console.log(`${proc.name}: ${proc.status}`);
      }
    }

    await sandbox.kill();
    ```
  </Tab>
</Tabs>

## Complete Example

Here's a complete process management workflow:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox
    import time

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

    # Start multiple background tasks
    tasks = {
        'data-processing': 'import time; time.sleep(20); print("Data processed")',
        'ml-training': 'import time; time.sleep(30); print("Model trained")',
        'report-generation': 'import time; time.sleep(15); print("Report generated")'
    }

    process_ids = {}
    for name, code in tasks.items():
        result = sandbox.run_code_background(code, language='python', name=name)
        process_ids[name] = result['process_id']
        print(f"✅ Started: {name} (ID: {result['process_id']})")

    # Monitor all processes
    print("\n📊 Monitoring processes...")
    while True:
        all_processes = sandbox.list_processes()
        active = [
            p for p in all_processes 
            if p['process_id'] in process_ids.values() 
            and p['status'] in ['queued', 'running']
        ]
        
        if not active:
            break
        
        print(f"\nActive: {len(active)}/{len(tasks)}")
        for proc in active:
            name = proc.get('name', 'unknown')
            status = proc['status']
            print(f"  {name}: {status}")
        
        time.sleep(3)

    # Show final results
    print("\n📋 Final Status:")
    all_processes = sandbox.list_processes()
    for name, proc_id in process_ids.items():
        proc = next((p for p in all_processes if p['process_id'] == proc_id), None)
        if proc:
            status_icon = {
                'completed': '✅',
                'failed': '❌',
                'killed': '🛑'
            }.get(proc['status'], '⏳')
            
            print(f"{status_icon} {name}: {proc['status']}")
            if proc['status'] == 'completed' and proc.get('stdout'):
                print(f"   Output: {proc['stdout'].strip()}")

    sandbox.kill()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

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

    // Start multiple background tasks
    const tasks = {
      'data-processing': 'import time; time.sleep(20); print("Data processed")',
      'ml-training': 'import time; time.sleep(30); print("Model trained")',
      'report-generation': 'import time; time.sleep(15); print("Report generated")'
    };

    const processIds = {};
    for (const [name, code] of Object.entries(tasks)) {
      const result = await sandbox.runCodeBackground(code, {
        language: 'python',
        name: name
      });
      processIds[name] = result.processId;
      console.log(`✅ Started: ${name} (ID: ${result.processId})`);
    }

    // Monitor all processes
    console.log('\n📊 Monitoring processes...');
    while (true) {
      const allProcesses = await sandbox.listProcesses();
      const active = allProcesses.filter(
        p => Object.values(processIds).includes(p.processId) &&
        ['queued', 'running'].includes(p.status)
      );
      
      if (active.length === 0) {
        break;
      }
      
      console.log(`\nActive: ${active.length}/${Object.keys(tasks).length}`);
      for (const proc of active) {
        console.log(`  ${proc.name}: ${proc.status}`);
      }
      
      await new Promise(resolve => setTimeout(resolve, 3000));
    }

    // Show final results
    console.log('\n📋 Final Status:');
    const finalProcesses = await sandbox.listProcesses();
    for (const [name, procId] of Object.entries(processIds)) {
      const proc = finalProcesses.find(p => p.processId === procId);
      if (proc) {
        const statusIcon = {
          'completed': '✅',
          'failed': '❌',
          'killed': '🛑'
        }[proc.status] || '⏳';
        
        console.log(`${statusIcon} ${name}: ${proc.status}`);
        if (proc.status === 'completed' && proc.stdout) {
          console.log(`   Output: ${proc.stdout.trim()}`);
        }
      }
    }

    await sandbox.kill();
    ```
  </Tab>
</Tabs>

## Best Practices

<Steps>
  <Step title="1. Name Your Processes">
    Always name processes when starting them for easier identification in process lists.
  </Step>

  <Step title="2. Monitor Regularly">
    Check process status periodically to track progress and detect failures early.
  </Step>

  <Step title="3. Clean Up Completed Processes">
    Remove or archive completed processes to keep your process list manageable.
  </Step>

  <Step title="4. Handle Failures">
    Check for failed status and access stderr for error details when processes fail.
  </Step>

  <Step title="5. Kill Stuck Processes">
    Use `kill_process()` to terminate processes that are stuck or taking too long.
  </Step>
</Steps>

## Related

* **[Background Execution](/core-concepts/code-execution/background)** - Start background processes
* **[Process Monitoring](/core-concepts/observability/processes)** - Monitor system processes
* **SDK**: [sandbox.list\_processes()](/sdk/python/sandbox#list_processes) - Python SDK method
* **SDK**: [sandbox.kill\_process()](/sdk/python/sandbox#kill_process) - Python SDK method
* **API**: [GET /execute/processes](/api/vm-agent/list-processes) - VM Agent API endpoint
* **API**: [DELETE /execute/kill](/api/vm-agent/kill-process) - VM Agent API endpoint
* [CLI Code Execution](/cli/commands/run) - Execute code from CLI

## Next Steps

* Learn about [Background Execution](/core-concepts/code-execution/background) to start processes
* Explore [Synchronous Execution](/core-concepts/code-execution/synchronous) for immediate results
* Review [Streaming Execution](/core-concepts/code-execution/streaming) for real-time monitoring