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

JavaScript
// Stop specific process
await sandbox.killProcess(server.id);


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


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

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