Background

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:

Python
JavaScript

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:

Python
JavaScript

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:

Python
JavaScript

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:

Python
JavaScript

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:

Python
JavaScript

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:

Python
JavaScript

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.

Running Commands - Execute commands synchronously
Process Monitoring - Monitor background processes
SDK: sandbox.commands.run_background() - Python SDK method
API: POST /commands/background - VM Agent API endpoint

Next Steps

Learn about Running Commands for synchronous execution
Explore Process Management to monitor background processes
Review Code Execution for background code execution

CLI Commands - Shell commands from CLI

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Overview

Starting Background Commands

Checking Process Status

Long-Running Servers

Environment Variables

Timeout Configuration

Complete Example

Best Practices

Next Steps

​Overview

​Starting Background Commands

​Checking Process Status

​Long-Running Servers

​Environment Variables

​Timeout Configuration

​Complete Example

​Best Practices

​Related

​Next Steps

​Related

Overview

Starting Background Commands

Checking Process Status

Long-Running Servers

Environment Variables

Timeout Configuration

Complete Example

Best Practices

Related

Next Steps

Related