Background

Background execution allows you to start code execution and return immediately, without waiting for completion. This is ideal for long-running tasks that you want to monitor and manage separately.

Prerequisites

Before you begin, make sure you have:

Active sandbox - A running sandbox (see Creating Sandboxes)
Understanding of synchronous execution - Familiarity with Synchronous Execution is helpful
Long-running task - Code that takes more than a few minutes to complete

Overview

Background execution is perfect for:

Long-running computations (>5 minutes)
Tasks that don’t need immediate results
Parallel processing of multiple tasks
Workflows where you want to check status periodically

Background execution returns immediately with a process_id. Use Process Management to check status and manage background processes.

Starting Background Execution

Start code execution in the background:

Python
JavaScript

from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# Start background execution
result = sandbox.run_code_background(
    code='''
import time
for i in range(10):
    print(f"Step {i+1}/10")
    time.sleep(2)
print("Done!")
''',
    language='python',
    name='long-task'
)

process_id = result['process_id']
print(f"Process started: {process_id}")
print(f"Status: {result['status']}")

sandbox.kill()

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({ template: 'code-interpreter' });

// Start background execution
const result = await sandbox.runCodeBackground(
  `
import time
for i in range(10):
    print(f"Step {i+1}/10")
    time.sleep(2)
print("Done!")
`,
  {
    language: 'python',
    name: 'long-task'
  }
);

const processId = result.processId;
console.log(`Process started: ${processId}`);
console.log(`Status: ${result.status}`);

await sandbox.kill();

Checking Process Status

Check the status of background processes:

Python
JavaScript

from hopx_ai import Sandbox
import time

sandbox = Sandbox.create(template="code-interpreter")

# Start background task
result = sandbox.run_code_background(
    code='import time; time.sleep(30); print("Done")',
    language='python',
    name='check-status-demo'
)

process_id = result['process_id']

# Check status periodically
for i in range(5):
    processes = sandbox.list_processes()
    for proc in processes:
        if proc['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 task
const result = await sandbox.runCodeBackground(
  'import time; time.sleep(30); print("Done")',
  {
    language: 'python',
    name: 'check-status-demo'
  }
);

const processId = result.processId;

// Check status periodically
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();

Process Naming

Name your processes for easier identification:

Python
JavaScript

from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# Start multiple named processes
proc1 = sandbox.run_code_background(
    code='import time; time.sleep(60)',
    language='python',
    name='data-processing'
)

proc2 = sandbox.run_code_background(
    code='import time; time.sleep(60)',
    language='python',
    name='ml-training'
)

# List processes by name
processes = sandbox.list_processes()
for proc in processes:
    print(f"{proc.get('name', 'unnamed')}: {proc['status']}")

sandbox.kill()

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({ template: 'code-interpreter' });

// Start multiple named processes
const proc1 = await sandbox.runCodeBackground(
  'import time; time.sleep(60)',
  {
    language: 'python',
    name: 'data-processing'
  }
);

const proc2 = await sandbox.runCodeBackground(
  'import time; time.sleep(60)',
  {
    language: 'python',
    name: 'ml-training'
  }
);

// List processes by name
const processes = await sandbox.listProcesses();
for (const proc of processes) {
  console.log(`${proc.name || 'unnamed'}: ${proc.status}`);
}

await sandbox.kill();

Environment Variables

Pass environment variables to background execution:

Python
JavaScript

from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# Start background task with environment variables
result = sandbox.run_code_background(
    code='''
import os
import time

api_key = os.getenv("API_KEY")
print(f"Using API key: {api_key[:10]}...")
time.sleep(30)
print("Task completed")
''',
    language='python',
    env={
        "API_KEY": "sk-123456",
        "DEBUG": "true"
    },
    name='env-demo'
)

print(f"Process ID: {result['process_id']}")

sandbox.kill()

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({ template: 'code-interpreter' });

// Start background task with environment variables
const result = await sandbox.runCodeBackground(
  `
import os
import time

api_key = os.getenv("API_KEY")
print(f"Using API key: {api_key[:10]}...")
time.sleep(30)
print("Task completed")
`,
  {
    language: 'python',
    env: {
      API_KEY: 'sk-123456',
      DEBUG: 'true'
    },
    name: 'env-demo'
  }
);

console.log(`Process ID: ${result.processId}`);

await sandbox.kill();

Timeout Configuration

Set timeout for background execution:

Python
JavaScript

from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# Start background task with 10 minute timeout
result = sandbox.run_code_background(
    code='import time; time.sleep(300)',
    language='python',
    timeout=600,  # 10 minutes
    name='long-task'
)

print(f"Process started with {result.get('timeout', 'default')}s timeout")

sandbox.kill()

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({ template: 'code-interpreter' });

// Start background task with 10 minute timeout
const result = await sandbox.runCodeBackground(
  'import time; time.sleep(300)',
  {
    language: 'python',
    timeout: 600,  // 10 minutes
    name: 'long-task'
  }
);

console.log(`Process started with ${result.timeout || 'default'}s timeout`);

await sandbox.kill();

Complete Example

Here’s a complete example showing background execution workflow:

Python
JavaScript

from hopx_ai import Sandbox
import time

sandbox = Sandbox.create(template="code-interpreter")

# Start background task
result = sandbox.run_code_background(
    code='''
import time
import random

for i in range(20):
    value = random.randint(1, 100)
    print(f"Step {i+1}: Generated {value}")
    time.sleep(1)
print("All done!")
''',
    language='python',
    timeout=300,
    name='random-generator',
    env={"SEED": "42"}
)

process_id = result['process_id']
print(f"✅ Background task started: {process_id}")

# Monitor progress
while True:
    processes = sandbox.list_processes()
    proc = next((p for p in processes if p['process_id'] == process_id), None)
    
    if not proc:
        print("Process not found")
        break
    
    status = proc['status']
    print(f"Status: {status}")
    
    if status == 'completed':
        print(f"✅ Task completed!")
        print(f"Output:\n{proc.get('stdout', '')}")
        break
    elif status == 'failed':
        print(f"❌ Task failed!")
        print(f"Error: {proc.get('stderr', '')}")
        break
    
    time.sleep(2)

sandbox.kill()

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({ template: 'code-interpreter' });

// Start background task
const result = await sandbox.runCodeBackground(
  `
import time
import random

for i in range(20):
    value = random.randint(1, 100)
    print(f"Step {i+1}: Generated {value}")
    time.sleep(1)
print("All done!")
`,
  {
    language: 'python',
    timeout: 300,
    name: 'random-generator',
    env: { SEED: '42' }
  }
);

const processId = result.processId;
console.log(`✅ Background task started: ${processId}`);

// Monitor progress
while (true) {
  const processes = await sandbox.listProcesses();
  const proc = processes.find(p => p.processId === processId);
  
  if (!proc) {
    console.log('Process not found');
    break;
  }
  
  const status = proc.status;
  console.log(`Status: ${status}`);
  
  if (status === 'completed') {
    console.log('✅ Task completed!');
    console.log(`Output:\n${proc.stdout || ''}`);
    break;
  } else if (status === 'failed') {
    console.log('❌ Task failed!');
    console.log(`Error: ${proc.stderr || ''}`);
    break;
  }
  
  await new Promise(resolve => setTimeout(resolve, 2000));
}

await sandbox.kill();

Best Practices

1. Use Descriptive Names

Always name your background processes for easier identification when listing and managing them.

2. Set Appropriate Timeouts

Set timeouts based on expected execution time. Default is 5 minutes, but you can extend for longer tasks.

3. Monitor Status Regularly

Check process status periodically to track progress and handle completion or failures.

4. Clean Up Completed Processes

Remove completed processes to keep your process list manageable. Use Process Management for cleanup.

5. Handle Failures

Always check for failed status and handle errors appropriately. Access stderr for error details.

Implementation

SDK: sandbox.run_code_background() - Python SDK method
CLI - Command-line interface
API: POST /execute/background - VM Agent API endpoint

Process Management - Monitor and manage background processes
Synchronous Execution - Execute code synchronously
Streaming Execution - Real-time output streaming
Async Execution with Webhooks - Very long-running tasks

Next Steps

Learn about Process Management to monitor and control background processes
Explore Async Webhooks for very long-running tasks (>30 minutes)
Review Synchronous Execution for immediate results

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Prerequisites

Overview

Starting Background Execution

Checking Process Status

Process Naming

Environment Variables

Timeout Configuration

Complete Example

Best Practices

Implementation

Next Steps

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

​Prerequisites

​Overview

​Starting Background Execution

​Checking Process Status

​Process Naming

​Environment Variables

​Timeout Configuration

​Complete Example

​Best Practices

​Implementation

​Related

​Next Steps

Prerequisites

Overview

Starting Background Execution

Checking Process Status

Process Naming

Environment Variables

Timeout Configuration

Complete Example

Best Practices

Implementation

Related

Next Steps