---
title: Real-time file watching in Sandboxes
description: sandbox.watch() returns an SSE stream of filesystem change events using native inotify, enabling real-time detection of file create, modify, delete, and move operations.
image: https://developers.cloudflare.com/changelog-preview.png
---

> Documentation Index  
> Fetch the complete documentation index at: https://developers.cloudflare.com/changelog/llms.txt  
> Use this file to discover all available pages before exploring further. 

[Skip to content](#%5Ftop) 

# Changelog

New updates and improvements at Cloudflare.

[ Subscribe to RSS ](https://developers.cloudflare.com/changelog/rss/index.xml) [ View RSS feeds ](https://developers.cloudflare.com/fundamentals/new-features/available-rss-feeds/) 

![hero image](https://developers.cloudflare.com/_astro/hero.CVYJHPAd_26AMqX.svg) 

[ ← Back to all posts ](https://developers.cloudflare.com/changelog/) 

## Real-time file watching in Sandboxes

Mar 03, 2026 

[ Agents ](https://developers.cloudflare.com/agents/) 

[Sandboxes](https://developers.cloudflare.com/sandbox/) now support real-time filesystem watching via `sandbox.watch()`. The method returns a [Server-Sent Events ↗](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent%5Fevents) 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 ](#tab-panel-2659)
* [  TypeScript ](#tab-panel-2660)

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 ](#tab-panel-2661)
* [  TypeScript ](#tab-panel-2662)

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

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

Terminal window

```
npm i @cloudflare/sandbox@latest
```

For full API details, refer to the [Sandbox file watching reference](https://developers.cloudflare.com/sandbox/api/file-watching/).

```json
{"@context":"https://schema.org","@type":"BlogPosting","@id":"https://developers.cloudflare.com/changelog/post/2026-03-03-sandbox-watch-file-events/#page","headline":"Real-time file watching in Sandboxes · Changelog","description":"sandbox.watch() returns an SSE stream of filesystem change events using native inotify, enabling real-time detection of file create, modify, delete, and move operations.","url":"https://developers.cloudflare.com/changelog/post/2026-03-03-sandbox-watch-file-events/","inLanguage":"en","image":"https://developers.cloudflare.com/changelog-preview.png","dateModified":"2026-03-03","datePublished":"2026-03-03","publisher":{"@type":"Organization","name":"Cloudflare","url":"https://www.cloudflare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}
```