DocsDigest
Back to listLanguage: JA
OpenAICloudflare Developer PlatformMar 3, 2026, 12:00 AM

Agents - Real-time file watching in Sandboxes

A condensed section focused on the key takeaways first.

Original Post
OpenAIClaude

Quick Digest

Summary

A condensed section focused on the key takeaways first.

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

Agents - Real-time file watching in Sandboxes

agentssandboxesssefile-watchinginotifyworkersjavascripttypescript

Key Points

  • SSE ReadableStream from sandbox.watch()
  • Supports create/modify/delete/move events
  • Use parseSSEStream for worker-side iteration

Summary

Sandboxes now provide real-time filesystem watching via sandbox.watch(path, options). The call returns a Server-Sent Events (SSE) ReadableStream backed by native inotify so your Worker can receive create, modify, delete, and move events as they happen inside the container. Move events include a from field with the original path.

Key Points

  • API: await sandbox.watch(path, { recursive?, include? }) returns an SSE ReadableStream.
  • Events: create, modify, delete, move (move includes from).
  • Options: recursive (boolean, default false) to watch subdirectories; include (string[]) accepts glob filters — omit to receive all events.
  • Client streaming: proxy the stream directly to a browser using a Response with Content-Type: text/event-stream.
// Stream events to a browser
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: use parseSSEStream to iterate events inside the Worker without forwarding.
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);
}
  • Upgrade: npm i @cloudflare/sandbox@latest.

References

  • See the Sandbox file watching reference in the docs for full API details.

Full Translation

Translations

A translation section that keeps the flow of the original article.

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 を参照してください。