> ## Documentation Index
> Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Watch

> Stream file system events from a sandbox directory or path

Use file watches when you need change notifications from inside a running sandbox.

## Watch A Directory

<CodeGroup>
  ```typescript Node.js theme={null}
  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();
  ```

  ```python Python theme={null}
  def on_event(event):
      print(event.type, event.name)

  handle = sandbox.files.watch_dir(
      "/tmp/watch",
      on_event,
      recursive=True,
  )

  sandbox.files.write_text("/tmp/watch/example.txt", "hello")
  handle.stop()
  ```

  ```bash CLI theme={null}
  hx file watch <sandbox-id> /tmp/watch --recursive
  ```
</CodeGroup>

## 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:

```text theme={null}
<seq>    <op>    <path>
```

## Resume From A Cursor

If you are consuming watch events from the CLI, you can resume from a known cursor:

```bash theme={null}
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.