Process Management

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

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

Listing Processes

List all background execution processes:

Python
JavaScript

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

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

Process Status

Check detailed status of processes:

Python
JavaScript

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

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

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

Python
JavaScript

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

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

Killing Processes

Terminate running processes:

Python
JavaScript

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

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

Monitoring Multiple Processes

Monitor multiple processes simultaneously:

Python
JavaScript

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

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

Complete Example

Here’s a complete process management workflow:

Python
JavaScript

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

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

Best Practices

1. Name Your Processes

Always name processes when starting them for easier identification in process lists.

2. Monitor Regularly

Check process status periodically to track progress and detect failures early.

3. Clean Up Completed Processes

Remove or archive completed processes to keep your process list manageable.

4. Handle Failures

Check for failed status and access stderr for error details when processes fail.

5. Kill Stuck Processes

Use kill_process() to terminate processes that are stuck or taking too long.

Background Execution - Start background processes
Process Monitoring - Monitor system processes
SDK: sandbox.list_processes() - Python SDK method
SDK: sandbox.kill_process() - Python SDK method
API: GET /execute/processes - VM Agent API endpoint
API: DELETE /execute/kill - VM Agent API endpoint
CLI Code Execution - Execute code from CLI

Next Steps

Learn about Background Execution to start processes
Explore Synchronous Execution for immediate results
Review Streaming Execution for real-time monitoring

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Overview

Listing Processes

Process Status

Process States

Killing Processes

Monitoring Multiple Processes

Complete Example

Best Practices

Next Steps

​Overview

​Listing Processes

​Process Status

​Process States

​Killing Processes

​Monitoring Multiple Processes

​Complete Example

​Best Practices

​Related

​Next Steps

Overview

Listing Processes

Process Status

Process States

Killing Processes

Monitoring Multiple Processes

Complete Example

Best Practices

Related

Next Steps