Skip to content
Cloudflare Docs

Run background processes

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

Start a background process

JavaScript
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

Configure process environment

Set working directory and environment variables:

JavaScript
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");

Monitor process status

List and check running processes:

JavaScript
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",
);

Wait for process readiness

Wait for a process to be ready before proceeding:

JavaScript
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");

Or wait for specific log patterns:

JavaScript
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);

Monitor process logs

Stream logs in real-time:

JavaScript
import { parseSSEStream } 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);
}

Or get accumulated logs:

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

Stop processes

Stop background processes and their children:

JavaScript
// 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();

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:

JavaScript
// 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);

Run multiple processes

Start services in sequence, waiting for dependencies:

JavaScript
// 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");

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:

JavaScript
import { getSandbox, parseSSEStream } from "@cloudflare/sandbox";


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


export default {
  async fetch(request, env) {
    // 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(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();
    }
  },
};

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:

JavaScript
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);
}

Port already in use

Kill existing processes before starting:

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