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 client
  const 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 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.

• 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 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

Upgrade

To update to the latest version:

npm i @cloudflare/sandbox@latest

For full API details, refer to the Sandbox file watching reference.

Source: Cloudflare

Latest Posts