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.

// Stream events to a browser client
const stream = await sandbox.watch("/workspace/src", {
	recursive: true,
	include: ["*.ts", "*.js"],
});

return new Response(stream, {
	headers: { "Content-Type": "text/event-stream" },
});

// Stream events to a browser client
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 with parseSSEStream

Use parseSSEStream to iterate over events inside a Worker without forwarding them to a client.

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

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 parseSSEStream<FileWatchSSEEvent>(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

Option Type Description recursive boolean Watch subdirectories. Defaults to false. include string[] 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.