Skip to main content
Use file watches when you need change notifications from inside a running sandbox.

​
Watch A Directory

const handle = await sandbox.files.watchDir(
  "/tmp/watch",
  async (event) => {
    console.log(event.type, event.name);
  },
  {
    recursive: true,
  }
);

await sandbox.files.writeText("/tmp/watch/example.txt", "hello");
await handle.stop();

​
Event Model

Watch events are emitted as the filesystem changes. The current runtime watch stream includes event sequence numbers, operation types, and the affected path. The CLI prints them in this form: 
<seq>    <op>    <path>

​
Resume From A Cursor

If you are consuming watch events from the CLI, you can resume from a known cursor: 
hx file watch <sandbox-id> /tmp/watch --recursive --from-cursor 120

​
When To Use Watches

Use watches when you need to:
  • React to generated outputs.
  • Detect file writes from background processes.
  • Build tail-like workflows around a sandbox workspace.
  • Feed change streams into higher-level orchestration.