Cloudflare Sandbox SDK

The Sandbox SDK uses a mutex-based concurrency model to manage command execution within sessions.

Per-Session Serialization

Each session has its own mutex. This ensures that commands within the same session are serialized (run one at a time, in order), while commands in different sessions can run in parallel.

Lock Release Strategies

• Foreground Commands (execStream): The session lock is held for the entire duration of the command. This prevents other commands from interleaving output while a user is actively watching the stream.
• Background Commands (startProcess): The session lock is released immediately after the command successfully starts and its PID is captured. This allows other commands to be issued to the same session while the background process (e.g., a server) continues to run.

Kill Operations

killCommand() does not acquire the session lock. This is critical to prevent deadlocks: if a command is stuck in an infinite loop and holding the lock, the user must still be able to issue a kill command to break the loop.

When terminating a process, simply killing the parent PID is insufficient because child processes will be orphaned and adopted by init (PID 1), continuing to run in the background.

To prevent this, the SDK performs a depth-first walk of the process tree using /proc to ensure children are killed before their parents. This ensures the relationship is still visible to the OS during the teardown.

The Kill Sequence:

1. Send SIGTERM to the entire tree to allow graceful cleanup.
2. Wait for a timeout (e.g., 5 seconds).
3. If processes remain, perform a re-walk of the tree and send SIGKILL to all identified descendants and the original root PID.

// Example of the depth-first kill logic used internally
const killTree = (targetPid: number, signal: NodeJS.Signals) => {
  try {
    // Read this process's children from /proc
    const childrenFile = `/proc/${targetPid}/task/${targetPid}/children`;
    const children = readFileSync(childrenFile, 'utf8').trim().split(/\s+/);

    // Recursively kill children FIRST
    for (const childPid of children.filter(Boolean)) {
      killTree(parseInt(childPid, 10), signal);
    }
  } catch {
    // Process already exited, or /proc not available
  }

  // Then kill this process
  try {
    process.kill(targetPid, signal);
  } catch {
    // Process already exited
  }
};

The WebSocket Tunnel example demonstrates a Cloudflare Worker that tunnels WebSocket connections from a browser to a Bun server running inside a Cloudflare Sandbox using Cloudflare Tunnel.

Tunneling Modes

1. Quick Tunnels: By default, the worker uses sandbox.tunnels.get(port). This generates a fresh *.trycloudflare.com URL on every container restart with zero configuration.

2. Named Tunnels: If TUNNEL_NAME is provided along with a CLOUDFLARE_API_TOKEN, the worker uses sandbox.tunnels.get(port, { name: TUNNEL_NAME }). This binds a stable hostname <TUNNEL_NAME>.<zone> that survives container restarts. The SDK automatically rediscovers the tagged Cloudflare resources on re-run.

Lifecycle and Cleanup

• Persistence: Named tunnels and DNS records persist on Cloudflare across container restarts.
• Automatic Cleanup: Stopping the sandbox stops all associated tunnels, deleting the Cloudflare tunnel and DNS record for named tunnels.
• Manual Cleanup: You can trigger cleanup by calling sandbox.destroy(). In this example, a /destroy route is provided to perform this action.
• Note: You do not need to call sandbox.tunnels.destroy(port) separately unless you want to remove a single tunnel while keeping the sandbox running.

Sessions allow you to maintain separate execution contexts (working directories, environment variables, and shell state) within a single sandbox. This is useful for multi-user applications where you want to use one sandbox ID but keep user environments isolated.

Workflow:

1. Create: POST /v1/sandbox/:id/session returns a session ID (e.g., sess_abc123).
2. Use: Include the Session-Id: <session-id> header in subsequent /exec, /pty, and file operation requests.
3. Delete: DELETE /v1/sandbox/:id/session/:sid tears down the session.

Important Notes:

• Statelessness: If you do not provide a Session-Id header, requests are stateless and do not reuse the default shell session (e.g., cd commands won't persist).
• Ephemeral Nature: Custom sessions do not survive container sleep/restarts. If the container restarts, you must create a new session.
• Sandbox Destruction: Calling DELETE /v1/sandbox/:id kills all active sessions immediately.

# Create a session
curl -X POST http://localhost:8787/v1/sandbox/mfrggzdfmy2tqnrz/session \
  -H "Authorization: Bearer $SANDBOX_API_KEY"

# Use the session (using the returned ID)
curl -X POST http://localhost:8787/v1/sandbox/mfrggzdfmy2tqnrz/exec \
  -H "Authorization: Bearer $SANDBOX_API_KEY" \
  -H "Session-Id: sess_abc123" \
  -H "Content-Type: application/json" \
  -d '{"argv": ["ls"]}'