feat: add file watching capabilities with inotify support

[whoiskatrin]

User problems this solves

This feature is designed for concrete workflows, not just API surface:

1. Hot reload / dev servers — Trigger rebuilds or reloads when source files change.
2. Incremental indexing / analysis — Re-index only changed files instead of rescanning whole trees.
3. Test reruns — Re-run affected tests when test files or dependencies change.

API

import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
 
// watch() resolves only after the watcher is established on the filesystem.
// Callers can immediately perform actions that depend on the watch being active.
const stream = await sandbox.watch("/app/src", {
  recursive: true,
  include: ["*.ts", "*.js"],
});
 
// Consume the SSE stream with parseSSEStream
const controller = new AbortController();
for await (const event of parseSSEStream<FileWatchSSEEvent>(
  stream,
  controller.signal
)) {
  if (event.type === "event") {
    console.log(event.eventType, event.path);
    // e.g. "create" "/app/src/new-file.ts"
  }
}
 
// Cancel by aborting the signal — cleans up the watcher server-side
controller.abort();

Key behaviors

• Deterministic readiness: watch() blocks until the filesystem watcher is established. No need to scan for a watching event before performing actions.
• Stream-based: Returns ReadableStream<Uint8Array> consumed via parseSSEStream. This is the only viable approach given the RPC layer (AsyncIterable cannot cross the boundary).
• Cancellation via AbortSignal: parseSSEStream registers an abort listener that calls reader.cancel(), which propagates server-side cleanup. No explicit stop endpoint needed.
• include/exclude are mutually exclusive: Validated at the container layer since inotifywait does not support both simultaneously.

---

Event flow

inotifywait (container)
        ↓
WatchService emits SSE frames
        ↓
parseSSEStream yields typed events
        ↓
User iterates with for-await

---

Hardening included in this PR

• Watch setup correctness — Fails watch startup on setup timeout/error (does not emit false watching). watch() throws if the watcher fails to establish.
• Request validation — Validates path, recursive, include, exclude. Rejects both include and exclude together.
• Path safety — Normalizes watch paths and enforces /workspace boundary.
• Backpressure protection — Coalesces events and caps pending queue at 1000; logs dropped-event pressure.
• Stream cancellation cleanup — Client-side reader.cancel() or AbortSignal abort propagates to kill the inotifywait process server-side. No orphaned watchers.
• WS per-connection stream ownership — onClose only cancels streams belonging to the closing WebSocket connection, not all active streams.
• Glob behavior clarity — Supported syntax is intentionally limited (*, **, ?, path separators). Unsupported complex tokens are rejected via validation.

---

Reviewer notes

1) SDK watch client + readiness

• packages/sandbox/src/clients/watch-client.ts
• packages/sandbox/src/sandbox.ts
• Focus: waitForReadiness() reads chunks until watching event, returns wrapper stream that replays buffered data

2) SSE parser abort handling

• packages/sandbox/src/sse-parser.ts
• Focus: abort listener calls reader.cancel() to unblock idle streams; cleanup removes listener

3) Container watch routing/validation

• packages/sandbox-container/src/handlers/watch-handler.ts
• packages/sandbox-container/src/routes/setup.ts
• Focus: request validation, include/exclude mutual exclusivity, path normalization

4) Watch process + stream robustness

• packages/sandbox-container/src/services/watch-service.ts
• Focus: setup-timeout behavior, backpressure controls, stderr/watch process cleanup

5) WebSocket adapter stream ownership

• packages/sandbox-container/src/handlers/ws-adapter.ts
• Focus: per-connection activeStreams tracking, scoped cancellation on close

6) End-to-end coverage

• tests/e2e/file-watch-workflow.test.ts
• tests/e2e/test-worker/index.ts
• Focus: watch establishment, include/exclude, stream cancellation, error paths. Uses parseSSEStream + AbortSignal.timeout with no hardcoded delays.

---

Key design decisions

1. Stream-based, not handle-based — Raw SSE stream + parseSSEStream is the only approach that works across the RPC boundary. No onEvent callback or watcher.stop().
2. Deterministic readiness — watch() blocks until established so callers know the watcher is active before performing filesystem actions.
3. Cancellation via signal, not stop endpoint — Aborting the AbortSignal or canceling the stream reader propagates cleanup. No /api/watch/stop needed.
4. Operationally safe defaults — Timeouts, cleanup, bounded buffering (max 1000 pending events).
5. Explicit validation and constrained pattern support — Predictable behavior over silent surprises.'

[changeset-bot]

🦋 Changeset detected

Latest commit: 6b88d36

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudflare/sandbox	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/sandbox-sdk/@cloudflare/sandbox@324

commit: 6b88d36

[github-actions]

🐳 Docker Images Published

Default:

FROM cloudflare/sandbox:0.0.0-pr-324-ff19085

With Python:

FROM cloudflare/sandbox:0.0.0-pr-324-ff19085-python

With OpenCode:

FROM cloudflare/sandbox:0.0.0-pr-324-ff19085-opencode

Version: 0.0.0-pr-324-ff19085

Use the -python variant if you need Python code execution, or -opencode for the variant with OpenCode AI coding agent pre-installed.

---

📦 Standalone Binary

For arbitrary Dockerfiles:

COPY --from=cloudflare/sandbox:0.0.0-pr-324-ff19085 /container-server/sandbox /sandbox
ENTRYPOINT ["/sandbox"]

Download via GitHub CLI:

gh run download 22590042787 -n sandbox-binary

Extract from Docker:

docker run --rm cloudflare/sandbox:0.0.0-pr-324-ff19085 cat /container-server/sandbox > sandbox && chmod +x sandbox

[parssak]

hey! I noticed there are docs for this but doesn't seem like the changes are live yet

would love to use this API, any timelines on when this'll get merged?

[whoiskatrin]

/bonk resolve conflict and review this PR

[ask-bonk]

Merge Conflict Resolved + Code Review

Conflict Resolution

Resolved the merge conflict in packages/sandbox-container/src/core/container.ts. The conflict was between the feature branch's watchHandler and main's ptyWsHandler — both are needed, so I included both in the Dependencies interface, the initialize() method, and the dependency registration block.

Build/typecheck/lint/unit tests all pass after the merge.

---

Code Review

Overall this is a well-architected feature that follows the three-layer SDK pattern correctly. The SSE streaming approach, DI integration, client pattern, and type safety are all solid. There are however several issues worth addressing, roughly in order of priority.

Issues to Address Before Merge

1. Empty catch blocks in cleanup paths (multiple locations)

Several catch blocks silently swallow errors that could indicate real problems:

• watch-service.ts:390-393 — proc.kill() in the finally block catches everything with just a comment "Process may already be dead". This hides permission errors (EPERM), system failures, etc. At minimum log at debug level and distinguish ESRCH (expected) from other errors.

• watch-service.ts:477 — Controller enqueue failure caught silently. Could lose error messages from inotifywait.

• watch-service.ts:563 — Same pattern in continueStderrMonitoring.

• file-watch.ts:168 — this.reader.cancel().catch(() => {}) in the finally block.

Per AGENTS.md: "silent failures are unacceptable." These should at minimum log at debug level.

2. FileWatch.established() can hang forever with AbortSignal

file-watch.ts:115-129 — If the watch is cancelled via AbortSignal during establishment before receiving the "watching" event, the runLoop throws and calls establishedReject, which is correct. However, if abort fires after established() is called but before the runLoop picks it up, there's a window where the promise could hang. The runLoop does check signal.aborted in the while condition, but if reader.read() is blocked waiting for data, the abort won't interrupt it until data arrives or the stream ends.

Consider adding a timeout or connecting the abort signal to reject the establishment promise directly.

3. isFileWatchSSEEvent type guard is weak

file-watch.ts:175-180 — Only validates that type is a string in the allowed set, but doesn't validate that required fields exist for each event type. For event type events, eventType, path, and isDirectory could all be undefined, leading to runtime errors or silent data loss when passed to onEvent callback.

4. Changeset description is implementation-focused

Per AGENTS.md: changesets should be user-facing with clear benefit and usage example. Current:

feat: add file watching capabilities with inotify support

Should explain benefit and show usage:

Add real-time file watching for detecting filesystem changes as they happen.

Use `sandbox.watch()` to monitor directories for create, modify, delete, and rename events:
const watcher = await sandbox.watch('/app/src', {
  recursive: true,
  onEvent: (event) => console.log(event.type, event.path),
});
await watcher.stop();

5. Debug logging left in E2E tests

file-watch-workflow.test.ts:204,257,404-408,436,451-452,485-488 — Multiple console.log('[DEBUG]...') statements should be removed before merge. Other E2E tests in the codebase don't have debug logging.

6. stopWatch uses UNKNOWN_ERROR instead of specific code

watch-service.ts:114 — When process.kill() fails in stopWatch(), it returns ErrorCode.UNKNOWN_ERROR. The codebase convention is to use specific error codes (like PROCESS_NOT_FOUND, PORT_NOT_EXPOSED). Consider adding WATCH_STOP_ERROR or reusing WATCH_START_ERROR (since it's a watch lifecycle error).

7. WatchService not integrated into server shutdown

The WatchService spawns inotifywait processes but there's no cleanup hook in packages/sandbox-container/src/server.ts. When the container shuts down, these processes could become zombies. Add watchService.stopAllWatches() to the server cleanup sequence.

Minor Items

• watch-service.ts:131-137 — Comments reference historical context ("Expected case: process already exited"). Per AGENTS.md, describe current behavior instead of referencing what the code prevents.

• E2E tests use fixed delays (1500ms, 3000ms) that could cause flakiness in slower CI environments. The watchWithActions helper's delays should be configurable or event-driven.

• file-watch.ts:189-191 — Malformed JSON is silently ignored with no logging. This makes debugging "missing events" very difficult in production. Consider logging at debug level.

Strengths

• Secure glob matching: Character-by-character regex construction with comprehensive ReDoS prevention tests is exemplary.
• State machine design in FileWatch: Clean establishing → active → stopped transitions with proper error handling at each transition.
• WatchService follows established patterns: DI via constructor injection, ServiceResult<T> return type, proper logger child creation.
• Comprehensive unit tests: Good coverage of glob matching, inotify event parsing, and argument building. Uses createNoOpLogger() as documented.
• E2E tests cover real workflows: Creation, modification, deletion, filtering, stop/list APIs, and error cases.
• Proper error codes: WATCH_NOT_FOUND and WATCH_START_ERROR with correct HTTP status mappings.
• WebSocket transport improvements: Partial SSE event state tracking across chunks is a correct fix for chunked event parsing.

[ask-bonk]

Done. Here's a summary of what I did:

Merge Conflict Resolution

Resolved the single conflict in packages/sandbox-container/src/core/container.ts where the feature branch added WatchHandler and main added PtyWebSocketHandler. Both were included in the merged result. The merge commit has been pushed.

Verification

• Biome lint: clean (295 files checked, no issues)
• TypeScript typecheck: all 14 packages pass
• Unit tests: all pass across all packages

Review Summary

The PR adds a well-architected file watching feature using inotify that follows the three-layer SDK pattern correctly. Key strengths include secure glob matching with ReDoS prevention, a clean state machine in FileWatch, and comprehensive test coverage.

7 issues identified ranging from silent error swallowing in cleanup paths, a potential hang in FileWatch.established() with AbortSignal, a weak type guard, implementation-focused changeset description, debug logging left in E2E tests, a generic error code where a specific one should be used, and missing server shutdown cleanup for watch processes. The full review is posted on the PR.

github run

[whoiskatrin]

hey! I noticed there are docs for this but doesn't seem like the changes are live yet

would love to use this API, any timelines on when this'll get merged?

really keen to get this in this week or next week. sorry about the docs, someone got them merged ahead of time

[ghostwriternr]

Biggest issue is perhaps confirming the API usage works as expected + some minor issues

[ghostwriternr]

I'm focusing this round of comments entirely on the E2E test - which as you've noticed is where I'm starting reviews for all new API surfaces - because it's the closest sign of how users would be experiencing the API. In this particular case, we seem to be doing a ton of extra work in the test layer because our SDK doesn't make it easy for the user. Furthermore, a lot of these issues also become apparent the moment I try to use the new APIs on the minimal example worker and notice there is no easy way to exit out of the watching loop because there is no easy way provided by the SDK to deterministically identify the terminal state.

The changes encouraged by the comments below would ideally need underlying changes - most prominently to our sse stream handling helper - and make user code cleaner + our tests deterministic and not flaky.

[ghostwriternr]

This helper is doing a very heavy lift here in place of the SDK. It is currently manually parsing SSE, manages reader lifecycle, detects readiness, handles timeouts, and collects typed events - all things parseSSEStream + watch() should provide out of the box.

I'd encourage comparing this to how something like execStream works: users call sandbox.execStream(), pipe through parseSSEStream(), and iterate typed events with for await, which is ~5 lines. The equivalent for watch() is users needing to write some version of this 90-line function.

If the goal is to provide the DX the original PR description promises (which also needs updating since the API surface has changed a bit due to the RPC constraints), watch() should return something users can consume with for await and an abort signal, just like execStream + parseSSEStream.

[ghostwriternr]

Our SDK currently exports parseSSEStream and even the JSDoc on the new watch() method recommends using it. But this test can't, because parseSSEStream doesn't currently support cancellation of long-lived streams. Its abort check only runs between reader.read() calls and on an idle watch stream, reader.read() blocks indefinitely, so the signal is never checked.

So maybe the hint here is to get parseSSEStream to register an abort listener that calls reader.cancel() when the signal fires, rather than polling signal.aborted between reads. It's probably just a one-line fix (signal.addEventListener('abort', () => reader.cancel())) (pls test properly though, I haven't tried this yet) that would make the entire watchWithActions helper unnecessary.

[ghostwriternr]

This is a manual reimplementation of AbortSignal.timeout() that this test has to do because passing AbortSignal.timeout(5000) to parseSSEStream doesn't actually cancel the stream (due to reasons I shared above). The "cancellable + resettable timeout" pattern is a major footgun because every user building a watch UI will need to solve the same "how do I stop listening after N seconds of inactivity" problem.

Once parseSSEStream handles abort correctly, this likely just becomes AbortSignal.timeout(timeoutMs) and need zero custom code.

[ghostwriternr]

As per the latest design, watch resolves immediately with a raw ReadableStream before the watcher is established on the filesystem. So this test has to manually scan the SSE stream for the watching event to know it's safe to create files — which is a bit absurd.

IMO, watch should either not resolve until the watcher is established (like how exec doesn't resolve until the command finishes), so that users don't need to write their own readiness-detection loop.

[ghostwriternr]

Any time we are using magic timeouts, that's a big code/design smell imo.

[ghostwriternr]

In fact, the more I'm reading this test file, I'm noticing there are 6 different hardcoded delays, all compensating for the lack of a readiness signal and event delivery guarantees. This 1500ms pre-action sleep is especially telling because the test already received the watching event but still doesn't trust that the watcher is ready. And the 3000ms one suggests we don't have a way to even confirm event delivery?

These are the kind of things that don't just make our CI flaky, but also user production code.

[ghostwriternr]

This comment applies here, as well as the should exclude patterns from events test below.

These two tests carefully avoid combining both include and exclude. And the reason is because the test worker has this line:

exclude: body.include ? [] : body.exclude,

The test worker silently drops exclude whenever include is present because inotifywait doesn't support both simultaneously. But WatchOptions accepts both include and exclude and nothing in the type specification or elsewhere tells users they're mutually exclusive.

We should either make the type honest: use a discriminated union or overloads so include and exclude can't be specified together. OR - and this is what I'd prefer - implement the combination at the SDK/container layer by maybe filtering in the SSE emitter if inotify can't handle it.

We shouldn't be hiding these behaviours in the test worker.

[ghostwriternr]

One more sign of even the simplest test to start a watch, then stop it can't use parseSSEStream. It has to manually read chunks and do string matching instead of iterating typed events. Further evidence that parseSSEStream's abort handling is the cleanest place to improve things across the board.

[ghostwriternr]

This test checks for errors via HTTP status code, SSE stream content and stream exception. If this is intentional and necessary, a user calling sandbox.watch('/nonexistent') has to defend against all three paths and maybe a hint at the error handling story for watch not being properly done too.

[whoiskatrin]

/bonk check if I missed anything based on Naresh's last review

[ghostwriternr]

very minor comments, looks good overall

[ghostwriternr]

Should maybe use CONFIG.DEFAULT_CWD, considering the default cwd is configurable by the user?

[ghostwriternr]

Why string based matching, which can be flaky? I feel like for this whole loop we could be using one of our parsing utils considering it's just a readable stream?

[github-actions]

OpenCode Review

This PR adds comprehensive file watching functionality to the Sandbox SDK using Linux's native inotify system. The implementation is well-architected and follows established SDK patterns correctly.

Key Implementation Strengths

Architecture: Properly follows the three-layer pattern - WatchHandler in container, shared types, and integration points for future client work. The dependency injection integration is clean.

SSE Protocol: The new parseSSEFrames() utility in packages/shared/src/sse.ts is well-designed - it correctly handles partial events across chunk boundaries and follows the SSE spec properly.

WebSocket Streaming: The WebSocket adapter changes are particularly good. The stream cancellation handling (lines 471-509 in ws-adapter.ts) correctly pre-acquires the reader before async operations to avoid Bun's GC issues.

Error Handling: Comprehensive error codes added to shared types, proper validation in the handler, and good path sandboxing to /workspace.

Testing: Excellent test coverage - both unit tests for individual components and E2E tests for the complete workflow.

Technical Implementation Quality

inotify Integration: Smart use of inotifywait with proper argument building. The event coalescing (75ms window) and backpressure handling (1000 event limit) show thoughtful performance considerations.

Glob Pattern Handling: The limitation to basic glob syntax (*, **, ?) with rejection of complex patterns is good for predictable performance.

Stream Lifecycle: The setup synchronization waiting for "Watches established" before resolving is the right approach for deterministic behavior.

Resource Management: Proper cleanup in both stream cancellation and server shutdown paths.

Documentation Impact

This introduces new public API surface that will need documentation. The API design is intuitive and follows existing patterns.

Verdict: Looks excellent and ready to merge. The implementation is production-ready with proper error handling, resource management, and test coverage.