Real-time File System Monitoring for Sandboxes

Cloudflare has introduced real-time file watching capabilities to its Sandbox product, enabling Workers to monitor filesystem changes inside containers as they happen. The new sandbox.watch() method returns a standard ReadableStream of Server-Sent Events, backed by native Linux inotify for efficient event delivery.

Key Features

• Event Types: Capture create, modify, delete, and move events with full path information
• SSE Integration: Stream events directly to browser clients or consume server-side
• Flexible Filtering: Support for recursive directory watching and glob pattern filtering via include option
• Simple API: Pass a directory path and optional configuration; move events include both source (from) and destination paths

Usage Patterns

Browser Streaming: Forward events directly to clients with a single line:

const stream = await sandbox.watch("/workspace/src", {
  recursive: true,
  include: ["*.ts", "*.js"],
});
return new Response(stream, {
  headers: { "Content-Type": "text/event-stream" },
});

Server-side Consumption: Process events inside Workers using the included parseSSEStream utility:

import { parseSSEStream } from "@cloudflare/sandbox";
const stream = await sandbox.watch("/workspace/src", { recursive: true });
for await (const event of parseSSEStream(stream)) {
  console.log(event.type, event.path);
}

Getting Started

Update the @cloudflare/sandbox package to the latest version:

npm i @cloudflare/sandbox@latest

This feature is particularly useful for development tooling, build systems, and real-time collaboration features running inside Cloudflare's edge infrastructure. Full API reference and TypeScript types are available in the Sandbox file watching documentation.