Skip to main content
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()

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

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

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

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

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

​
Best Practices

1

1. Name Your Processes

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

2. Monitor Regularly

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

3. Clean Up Completed Processes

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

4. Handle Failures

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

5. Kill Stuck Processes

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

​
Next Steps