Run shell commands in the background and return immediately. This is ideal for long-running commands that you want to monitor and manage separately.
Overview
Background command execution is perfect for:
- Long-running commands (>5 minutes)
- Server processes that need to keep running
- Commands that don’t need immediate results
- Parallel execution of multiple commands
Background commands return immediately with a process_id. Use process management to check status and manage background processes.
Starting Background Commands
Start a command in the background:
from hopx_ai import Sandbox
sandbox = Sandbox.create(template="code-interpreter")
# Start background command
result = sandbox.commands.run(
'sleep 30 && echo "Done!"',
background=True
)
# Extract process ID from output
process_id = result.stdout.split('cmd_')[-1].strip() if 'cmd_' in result.stdout else None
print(f"Process started: {process_id}")
print(f"Status: {result.stdout}")
sandbox.kill()
import { Sandbox } from '@hopx-ai/sdk';
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
// Start background command
const result = await sandbox.commands.runBackground(
'sleep 30 && echo "Done!"'
);
console.log(`Process started: ${result.processId}`);
console.log(`Status: ${result.status || 'running'}`);
await sandbox.kill();
Checking Process Status
Check the status of background commands:
from hopx_ai import Sandbox
import time
sandbox = Sandbox.create(template="code-interpreter")
# Start background command
result = sandbox.commands.run(
'sleep 30 && echo "Task completed"',
background=True
)
# Extract process ID
process_id = result.stdout.split('cmd_')[-1].strip() if 'cmd_' in result.stdout else None
# Check status using list_processes
for i in range(5):
processes = sandbox.list_processes()
for proc in processes:
if proc.get('process_id') == process_id:
print(f"Status: {proc['status']}")
if proc['status'] == 'completed':
print(f"Output: {proc.get('stdout', '')}")
break
time.sleep(2)
sandbox.kill()
import { Sandbox } from '@hopx-ai/sdk';
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
// Start background command
const result = await sandbox.commands.runBackground(
'sleep 30 && echo "Task completed"'
);
const processId = result.processId;
// Check status using listProcesses
for (let i = 0; i < 5; i++) {
const processes = await sandbox.listProcesses();
const proc = processes.find(p => p.processId === processId);
if (proc) {
console.log(`Status: ${proc.status}`);
if (proc.status === 'completed') {
console.log(`Output: ${proc.stdout || ''}`);
break;
}
}
await new Promise(resolve => setTimeout(resolve, 2000));
}
await sandbox.kill();
Long-Running Servers
Start long-running server processes:
from hopx_ai import Sandbox
import time
sandbox = Sandbox.create(template="code-interpreter")
# Start a web server in background
result = sandbox.commands.run(
'python -m http.server 8000',
background=True,
timeout=3600, # 1 hour
env={"PORT": "8000"}
)
process_id = result.stdout.split('cmd_')[-1].strip() if 'cmd_' in result.stdout else None
print(f"Server started: {process_id}")
# Check if server is running
time.sleep(2)
processes = sandbox.list_processes()
for proc in processes:
if proc.get('process_id') == process_id:
print(f"Server status: {proc['status']}")
sandbox.kill()
import { Sandbox } from '@hopx-ai/sdk';
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
// Start a web server in background
const result = await sandbox.commands.runBackground(
'python -m http.server 8000',
{
timeout: 3600, // 1 hour
env: { PORT: '8000' }
}
);
console.log(`Server started: ${result.processId}`);
// Check if server is running
await new Promise(resolve => setTimeout(resolve, 2000));
const processes = await sandbox.listProcesses();
const serverProc = processes.find(p => p.processId === result.processId);
if (serverProc) {
console.log(`Server status: ${serverProc.status}`);
}
await sandbox.kill();
Environment Variables
Pass environment variables to background commands:
from hopx_ai import Sandbox
sandbox = Sandbox.create(template="code-interpreter")
# Start background command with environment variables
result = sandbox.commands.run(
'python -c "import os, time; print(os.getenv(\'API_KEY\')); time.sleep(60)"',
background=True,
env={
"API_KEY": "sk-123456",
"DEBUG": "true"
}
)
print(f"Process started: {result.stdout}")
sandbox.kill()
import { Sandbox } from '@hopx-ai/sdk';
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
// Start background command with environment variables
const result = await sandbox.commands.runBackground(
'python -c "import os, time; print(os.getenv(\'API_KEY\')); time.sleep(60)"',
{
env: {
API_KEY: 'sk-123456',
DEBUG: 'true'
}
}
);
console.log(`Process started: ${result.processId}`);
await sandbox.kill();
Timeout Configuration
Set timeout for background commands:
from hopx_ai import Sandbox
sandbox = Sandbox.create(template="code-interpreter")
# Start background command with 10 minute timeout
result = sandbox.commands.run(
'long_running_task.sh',
background=True,
timeout=600 # 10 minutes
)
print(f"Process started with {600}s timeout")
sandbox.kill()
import { Sandbox } from '@hopx-ai/sdk';
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
// Start background command with 10 minute timeout
const result = await sandbox.commands.runBackground(
'long_running_task.sh',
{
timeout: 600 // 10 minutes
}
);
console.log(`Process started with 600s timeout`);
await sandbox.kill();
Complete Example
Here’s a complete example showing background command workflow:
from hopx_ai import Sandbox
import time
sandbox = Sandbox.create(template="code-interpreter")
# Start multiple background tasks
tasks = {
'data-processing': 'python process_data.py',
'ml-training': 'python train_model.py',
'report-generation': 'python generate_report.py'
}
process_ids = {}
print("🚀 Starting background tasks...\n")
for name, command in tasks.items():
result = sandbox.commands.run(
command,
background=True,
timeout=600,
env={"TASK_NAME": name}
)
process_id = result.stdout.split('cmd_')[-1].strip() if 'cmd_' in result.stdout else None
process_ids[name] = process_id
print(f"✅ Started: {name} (ID: {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.get('process_id') in process_ids.values()
and p.get('status') in ['queued', 'running']
]
if not active:
break
print(f"\nActive: {len(active)}/{len(tasks)}")
for proc in active:
name = next(k for k, v in process_ids.items() if v == proc.get('process_id'))
print(f" {name}: {proc['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.get('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()[:50]}...")
sandbox.kill()
import { Sandbox } from '@hopx-ai/sdk';
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
// Start multiple background tasks
const tasks = {
'data-processing': 'python process_data.py',
'ml-training': 'python train_model.py',
'report-generation': 'python generate_report.py'
};
const processIds = {};
console.log('🚀 Starting background tasks...\n');
for (const [name, command] of Object.entries(tasks)) {
const result = await sandbox.commands.runBackground(command, {
timeout: 600,
env: { TASK_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) {
const name = Object.keys(processIds).find(k => processIds[k] === proc.processId);
console.log(` ${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().substring(0, 50)}...`);
}
}
}
await sandbox.kill();
Best Practices
1. Extract Process IDs
Extract process IDs from the result to track and manage background commands.
2. Set Appropriate Timeouts
Set timeouts based on expected execution time. Default is 30 seconds, but increase for longer tasks.
3. Monitor Status Regularly
Check process status periodically to track progress and detect failures early.
4. Use Process Management
Use list_processes() and kill_process() to monitor and control background commands.
5. Handle Failures
Check for failed status and access stderr for error details when commands fail.
Next Steps
