Run background processes

import { TypeScriptExample, Render } from "~/components";

<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />

This guide shows you how to start, monitor, and manage long-running background processes in the sandbox.

When to use background processes

Use startProcess() instead of exec() when:

• Running web servers - HTTP servers, APIs, WebSocket servers
• Long-running services - Database servers, caches, message queues
• Development servers - Hot-reloading dev servers, watch modes
• Continuous monitoring - Log watchers, health checkers
• Parallel execution - Multiple services running simultaneously

:::note For one-time commands, builds, or scripts that complete and exit, use exec() instead. See the Execute commands guide. :::

Start a background process

``` import { getSandbox } from '@cloudflare/sandbox';

const sandbox = getSandbox(env.Sandbox, 'my-sandbox');

// Start a web server const server = await sandbox.startProcess('python -m http.server 8000');

console.log('Server started'); console.log('Process ID:', server.id); console.log('PID:', server.pid); console.log('Status:', server.status); // 'running'

// Process runs in background - your code continues

</TypeScriptExample>

## Configure process environment

Set working directory and environment variables:

<TypeScriptExample>

const process = await sandbox.startProcess('node server.js', { cwd: '/workspace/api', env: { NODE_ENV: 'production', PORT: '8080', API_KEY: env.API_KEY, DATABASE_URL: env.DATABASE_URL } });

console.log('API server started');

</TypeScriptExample>

## Monitor process status

List and check running processes:

<TypeScriptExample>

const processes = await sandbox.listProcesses();

console.log(Running ${processes.length} processes:);

for (const proc of processes) { console.log(${proc.id}: ${proc.command} (${proc.status})); }

// Check if specific process is running const isRunning = processes.some(p => p.id === processId && p.status === 'running');

</TypeScriptExample>

## Wait for process readiness

Wait for a process to be ready before proceeding:

<TypeScriptExample>

const server = await sandbox.startProcess('node server.js');

// Wait for server to respond on port 3000 await server.waitForPort(3000);

console.log('Server is ready');

</TypeScriptExample>

Or wait for specific log patterns:

<TypeScriptExample>

const server = await sandbox.startProcess('node server.js');

// Wait for log message const result = await server.waitForLog('Server listening'); console.log('Server is ready:', result.line);

</TypeScriptExample>

## Monitor process logs

Stream logs in real-time:

<TypeScriptExample>

import { parseSSEStream, type LogEvent } from '@cloudflare/sandbox';

const server = await sandbox.startProcess('node server.js');

// Stream logs const logStream = await sandbox.streamProcessLogs(server.id);

for await (const log of parseSSEStream(logStream)) { console.log(log.data); }

</TypeScriptExample>

Or get accumulated logs:

<TypeScriptExample>

const logs = await sandbox.getProcessLogs(server.id); console.log('Logs:', logs);

</TypeScriptExample>

## Stop processes

Stop background processes and their children:

<TypeScriptExample>

// Stop specific process (terminates entire process tree) await sandbox.killProcess(server.id);

// Force kill if needed await sandbox.killProcess(server.id, 'SIGKILL');

// Stop all processes await sandbox.killAllProcesses();

</TypeScriptExample>

`killProcess()` terminates the specified process and all child processes it spawned. This ensures that processes running in the background do not leave orphaned child processes when terminated.

For example, if your process spawns multiple worker processes or background tasks, `killProcess()` will clean up the entire process tree:

<TypeScriptExample>

// This script spawns multiple child processes const batch = await sandbox.startProcess( 'bash -c "process1 & process2 & process3 & wait"' );

// killProcess() terminates the bash process AND all three child processes await sandbox.killProcess(batch.id);

</TypeScriptExample>

## Run multiple processes

Start services in sequence, waiting for dependencies:

<TypeScriptExample>

// Start database first const db = await sandbox.startProcess('redis-server');

// Wait for database to be ready await db.waitForPort(6379, { mode: 'tcp' });

// Now start API server (depends on database) const api = await sandbox.startProcess('node api-server.js', { env: { DATABASE_URL: 'redis://localhost:6379' } });

// Wait for API to be ready await api.waitForPort(8080, { path: '/health' });

console.log('All services running');

</TypeScriptExample>

## Keep containers alive for long-running processes

By default, containers automatically shut down after 10 minutes of inactivity. For long-running processes that may have idle periods (like CI/CD pipelines, batch jobs, or monitoring tasks), use the [`keepAlive` option](/sandbox/sdk/configuration/sandbox-options/#keepalive):

<TypeScriptExample>
```ts
import { getSandbox, parseSSEStream, type LogEvent } from '@cloudflare/sandbox';

export { Sandbox } from '@cloudflare/sandbox';

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Enable keepAlive for long-running processes
    const sandbox = getSandbox(env.Sandbox, 'build-job-123', {
      keepAlive: true
    });

    try {
      // Start a long-running build process
      const build = await sandbox.startProcess('npm run build:production');

      // Monitor progress
      const logs = await sandbox.streamProcessLogs(build.id);

      // Process can run indefinitely without container shutdown
      for await (const log of parseSSEStream<LogEvent>(logs)) {
        console.log(log.data);
        if (log.data.includes('Build complete')) {
          break;
        }
      }

      return new Response('Build completed');
    } finally {
      // Important: Must explicitly destroy when done
      await sandbox.destroy();
    }
  }
};

:::caution[Always destroy with keepAlive] When using keepAlive: true, containers will not automatically timeout. You must call sandbox.destroy() when finished to prevent containers running indefinitely and counting toward your account limits. :::

Best practices

• Wait for readiness - Use waitForPort() or waitForLog() to detect when services are ready
• Clean up - Always stop processes when done
• Handle failures - Monitor logs for errors and restart if needed
• Use try/finally - Ensure cleanup happens even on errors
• Use keepAlive for long-running tasks - Prevent container shutdown during processes with idle periods

Troubleshooting

Process exits immediately

Check logs to see why:

``` const process = await sandbox.startProcess('node server.js'); await new Promise(resolve => setTimeout(resolve, 1000));

const processes = await sandbox.listProcesses(); if (!processes.find(p => p.id === process.id)) { const logs = await sandbox.getProcessLogs(process.id); console.error('Process exited:', logs); }

</TypeScriptExample>

### Port already in use

Kill existing processes before starting:

<TypeScriptExample>

await sandbox.killAllProcesses(); const server = await sandbox.startProcess('node server.js');

</TypeScriptExample>

## Related resources

- [Commands API reference](/sandbox/sdk/api/commands/) - Complete process management API
- [Sandbox options configuration](/sandbox/sdk/configuration/sandbox-options/) - Configure `keepAlive` and other options
- [Lifecycle API](/sandbox/sdk/api/lifecycle/) - Create and manage sandboxes
- [Sessions API reference](/sandbox/sdk/api/sessions/) - Create isolated execution contexts
- [Execute commands guide](/sandbox/sdk/guides/execute-commands/) - One-time command execution
- [Expose services guide](/sandbox/sdk/guides/expose-services/) - Make processes accessible
- [Streaming output guide](/sandbox/sdk/guides/streaming-output/) - Monitor process output