Filesystem supports directory change watching. This is useful for waiting for agent output files in long tasks, syncing artifacts generated by programs inside the sandbox, or forwarding file change events to a business-side state machine.
Watch a directory
TypeScript example:
const watcher = await sandbox.files.watchDir("/tmp/output", (event) => {
console.log(event);
});
// Stop watching after the task finishes.
await watcher.stop();onEvent is the second positional argument to watchDir(), not a field inside an options object. Optional settings such as recursive and onExit are passed through the third argument. Stop watching with watcher.stop().
The Python SDK uses watch_dir(), and the callback is passed through the positional on_event argument:
handle = sandbox.files.watch_dir(
"/tmp/output",
on_event=lambda event: print(event),
)
handle.stop()Before production use, validate the event shape, close behavior, and error responses with a minimal example.
Recommendations
Make sure the directory exists before watching it. You can create the output directory with
sandbox.files.makeDir().The callback may receive duplicate events. Deduplicate on the business side by file path, event type, and task ID.
Watching improves timeliness, but final task state should still be determined from the command exit code, a business state file, or external task state.
For long-running watchers, set a business timeout and stop the watcher when the task succeeds, fails, or times out.
If you only need to wait for a single file to appear, you can still use bounded polling with
sandbox.files.exists().