Summary

Sandboxesでsandbox.watch(path, options)が利用可能になりました。ネイティブinotifyをバックエンドとするServer-Sent Events (SSE) ストリームを返し、コンテナ内のファイル作成・変更・削除・移動イベントをリアルタイムで受信できます。戻り値は標準のReadableStreamで、ブラウザへプロキシするかワーカー内で直接消費できます。

Key Points

API: sandbox.watch(path, options) が ReadableStream（SSE）を返す
イベント種類: create, modify, delete, move（move は from フィールドを含む）
オプション:
- recursive (boolean、デフォルト false)
- include (string[]、globパターンでフィルタ。未指定で全イベント)
ブラウザへ転送例: return new Response(stream, { headers: { "Content-Type": "text/event-stream" } })
ワーカー内での処理例: for await (const event of parseSSEStream(stream)) { console.log(event.type, event.path) }
アップデート: npm i @cloudflare/sandbox@latest

Notes

フィルタはglobベースです。サブディレクトリも監視する場合は recursive: true を指定してください。

openaijamodel: gpt-5-mini-2025-08-07

Agents - サンドボックスでのリアルタイムファイル監視

サンドボックスでのリアルタイムファイル監視

Sandboxes は sandbox.watch() を介したリアルタイムのファイルシステム監視をサポートするようになりました。メソッドはネイティブの inotify をバックエンドに持つ Server-Sent Events ↗ ストリームを返すため、コンテナ内で発生する create、modify、delete、move イベントを Worker がその場で受け取れます。

使用法

sandbox.watch(path, options) にディレクトリパスとオプションのフィルタを渡します。返されるストリームは標準の ReadableStream で、ブラウザクライアントへ直接プロキシするかサーバー側で消費できます。

ブラウザへイベントをストリームする（JavaScript / 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" },
});

サーバー側での消費（parseSSEStream）

parseSSEStream を使うと、Worker 内でイベントを反送信せずに反復処理できます。

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

イベントの内容

type : イベント種別（create、modify、delete、move）。
path : 影響を受けたパス。
from : move イベントに含まれるフィールドで、元のパスを示します。

オプション

recursive (boolean) — サブディレクトリも監視します。デフォルトは false。
include (string[]) — イベントをフィルタする glob パターン。指定しないと全てのイベントを受け取ります。

アップグレード

最新バージョンに更新するには：

npm i @cloudflare/sandbox@latest

参照

フル API の詳細は Sandbox file watching reference を参照してください。

Agents - Real-time file watching in Sandboxes

要約