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:
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:
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 startrunning - Currently executingcompleted - Finished successfullyfailed - Execution failedkilled - Terminated by user
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:
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:
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:
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.
Next Steps
