Agents - Real-time file watching in Sandboxes

Sandboxes now support real-time filesystem watching via sandbox.watch(). The method returns a Server-Sent Events stream backed by native inotify, so your Worker receives create, modify, delete, and move events as they happen inside the container. sandbox.watch(path, options) Pass a directory path and optional filters. The returned stream is a standard ReadableStream you can proxy directly to a browser client or consume server-side. JavaScript // Stream events to a browser clientconst stream = await sandbox.watch("/workspace/src", { recursive: true, include: [".ts", ".js"],}); return new Response(stream, { headers: { "Content-Type": "text/event-stream" },}); TypeScript // Stream events to a browser clientconst stream = await sandbox.watch("/workspace/src", { recursive: true, include: [".ts", ".js"],}); return new Response(stream, { headers: { "Content-Type": "text/event-stream" },});
Server-side consumption with parseSSEStream Use parseSSEStream to iterate over events inside a Worker without forwarding them to a client. JavaScript 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);} TypeScript import { parseSSEStream } from "@cloudflare/sandbox";import type { FileWatchSSEEvent } from "@cloudflare/sandbox"; const stream = await sandbox.watch("/workspace/src", { recursive: true }); for await (const event of parseSSEStreamFileWatchSSEEvent>(stream)) { console.log(event.type, event.path);}
Each event includes a type field (create, modify, delete, or move) and the affected path. Move events also include a from field with the original path. Options

OptionTypeDescriptionrecursivebooleanWatch subdirectories. Defaults to false.includestring[]Glob patterns to filter events. Omit to receive all events. Upgrade To update to the latest version: npm i @cloudflare/sandbox@latest For full API details, refer to the Sandbox file watching reference.