Skip to content
Cloudflare Docs

Commands

Execute commands and manage background processes in the sandbox's isolated container environment.

Methods

exec()

Execute a command and return the complete result.

TypeScript
const result = await sandbox.exec(command: string, options?: ExecOptions): Promise<ExecuteResponse>

Parameters:

  • command - The command to execute (can include arguments)
  • options (optional):
    • stream - Enable streaming callbacks (default: false)
    • onOutput - Callback for real-time output: (stream: 'stdout' | 'stderr', data: string) => void
    • timeout - Maximum execution time in milliseconds

Returns: Promise<ExecuteResponse> with success, stdout, stderr, exitCode

JavaScript
const result = await sandbox.exec("npm run build");


if (result.success) {
  console.log("Build output:", result.stdout);
} else {
  console.error("Build failed:", result.stderr);
}


// With streaming
await sandbox.exec("npm install", {
  stream: true,
  onOutput: (stream, data) => console.log(`[${stream}] ${data}`),
});

execStream()

Execute a command and return a Server-Sent Events stream for real-time processing.

TypeScript
const stream = await sandbox.execStream(command: string, options?: ExecOptions): Promise<ReadableStream>

Parameters:

  • command - The command to execute
  • options - Same as exec()

Returns: Promise<ReadableStream> emitting ExecEvent objects (start, stdout, stderr, complete, error)

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


const stream = await sandbox.execStream("npm run build");


for await (const event of parseSSEStream(stream)) {
  switch (event.type) {
    case "stdout":
      console.log("Output:", event.data);
      break;
    case "complete":
      console.log("Exit code:", event.exitCode);
      break;
    case "error":
      console.error("Failed:", event.error);
      break;
  }
}

startProcess()

Start a long-running background process.

TypeScript
const process = await sandbox.startProcess(command: string, options?: ProcessOptions): Promise<Process>

Parameters:

  • command - The command to start as a background process
  • options (optional):
    • cwd - Working directory
    • env - Environment variables

Returns: Promise<Process> object with:

  • id - Unique process identifier
  • pid - System process ID
  • command - The command being executed
  • status - Current status ('running', 'exited', etc.)
  • kill() - Stop the process
  • getStatus() - Get current status
  • getLogs() - Get accumulated logs
  • waitForPort() - Wait for process to listen on a port
  • waitForLog() - Wait for pattern in process output
JavaScript
const server = await sandbox.startProcess("python -m http.server 8000");
console.log("Started with PID:", server.pid);


// With custom environment
const app = await sandbox.startProcess("node app.js", {
  cwd: "/workspace/my-app",
  env: { NODE_ENV: "production", PORT: "3000" },
});

listProcesses()

List all running processes.

TypeScript
const processes = await sandbox.listProcesses(): Promise<ProcessInfo[]>
JavaScript
const processes = await sandbox.listProcesses();


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

killProcess()

Terminate a specific process.

TypeScript
await sandbox.killProcess(processId: string, signal?: string): Promise<void>

Parameters:

  • processId - The process ID (from startProcess() or listProcesses())
  • signal - Signal to send (default: "SIGTERM")
JavaScript
const server = await sandbox.startProcess("python -m http.server 8000");
await sandbox.killProcess(server.id);

killAllProcesses()

Terminate all running processes.

TypeScript
await sandbox.killAllProcesses(): Promise<void>
JavaScript
await sandbox.killAllProcesses();

streamProcessLogs()

Stream logs from a running process in real-time.

TypeScript
const stream = await sandbox.streamProcessLogs(processId: string): Promise<ReadableStream>

Parameters:

  • processId - The process ID

Returns: Promise<ReadableStream> emitting LogEvent objects

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


const server = await sandbox.startProcess("node server.js");
const logStream = await sandbox.streamProcessLogs(server.id);


for await (const log of parseSSEStream(logStream)) {
  console.log(`[${log.timestamp}] ${log.data}`);


  if (log.data.includes("Server started")) break;
}

getProcessLogs()

Get accumulated logs from a process.

TypeScript
const logs = await sandbox.getProcessLogs(processId: string): Promise<string>

Parameters:

  • processId - The process ID

Returns: Promise<string> with all accumulated output

JavaScript
const server = await sandbox.startProcess("node server.js");
await new Promise((resolve) => setTimeout(resolve, 5000));


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

Process readiness methods

The Process object returned by startProcess() includes methods to wait for the process to be ready before proceeding.

process.waitForPort()

Wait for a process to listen on a port.

TypeScript
await process.waitForPort(port: number, options?: WaitForPortOptions): Promise<void>

Parameters:

  • port - The port number to check
  • options (optional):
    • mode - Check mode: 'http' (default) or 'tcp'
    • timeout - Maximum wait time in milliseconds
    • interval - Check interval in milliseconds (default: 100)
    • path - HTTP path to check (default: '/', HTTP mode only)
    • status - Expected HTTP status range (default: { min: 200, max: 399 }, HTTP mode only)

HTTP mode (default) makes an HTTP GET request and checks the response status:

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


// Wait for server to be ready (HTTP mode)
await server.waitForPort(3000);


// Check specific endpoint and status
await server.waitForPort(8080, {
  path: "/health",
  status: { min: 200, max: 299 },
  timeout: 30000,
});

TCP mode checks if the port accepts connections:

JavaScript
const db = await sandbox.startProcess("redis-server");


// Wait for database to accept connections
await db.waitForPort(6379, {
  mode: "tcp",
  timeout: 10000,
});

Throws:

  • ProcessReadyTimeoutError - If port does not become ready within timeout
  • ProcessExitedBeforeReadyError - If process exits before becoming ready

process.waitForLog()

Wait for a pattern to appear in process output.

TypeScript
const result = await process.waitForLog(pattern: string | RegExp, timeout?: number): Promise<WaitForLogResult>

Parameters:

  • pattern - String or RegExp to match in stdout/stderr
  • timeout - Maximum wait time in milliseconds (optional)

Returns: Promise<WaitForLogResult> with:

  • line - The matching line of output
  • matches - Array of capture groups (for RegExp patterns)
JavaScript
const server = await sandbox.startProcess("node server.js");


// Wait for string pattern
const result = await server.waitForLog("Server listening");
console.log("Ready:", result.line);


// Wait for RegExp with capture groups
const result = await server.waitForLog(/Server listening on port (\d+)/);
console.log("Port:", result.matches[1]); // Extracted port number


// With timeout
await server.waitForLog("Ready", 30000);

Throws:

  • ProcessReadyTimeoutError - If pattern is not found within timeout
  • ProcessExitedBeforeReadyError - If process exits before pattern appears