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

# Watch sandbox directory for changes

You can watch a directory for changes using the `files.watchDir()` method in JavaScript and `files.watch_dir()` method in Python.

<Note>
  Since events are tracked asynchronously, their delivery may be delayed.
  It's recommended not to collect or close watcher immediately after making a change.
</Note>

<CodeGroup>
  ```js JavaScript & TypeScript highlight={7-12} theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
  import { Sandbox, FilesystemEventType } from 'e2b'

  const sandbox = await Sandbox.create()
  const dirname = '/home/user'

  // Start watching directory for changes
  const handle = await sandbox.files.watchDir(dirname, async (event) => {
    console.log(event)
    if (event.type === FilesystemEventType.WRITE) {
      console.log(`wrote to file ${event.name}`)
    }
  })

  // Trigger file write event
  await sandbox.files.write(`${dirname}/my-file`, 'hello')
  ```

  ```python Python highlight={7,12-16} theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
  from e2b import Sandbox, FilesystemEventType

  sandbox = Sandbox.create()
  dirname = '/home/user'

  # Watch directory for changes
  handle = sandbox.files.watch_dir(dirname)
  # Trigger file write event
  sandbox.files.write(f"{dirname}/my-file", "hello")

  # Retrieve the latest new events since the last `get_new_events()` call
  events = handle.get_new_events()
  for event in events:
    print(event)
    if event.type == FilesystemEventType.WRITE:
      print(f"wrote to file {event.name}")
  ```
</CodeGroup>

## Recursive watching

You can enable recursive watching using the parameter `recursive`.

<Note>
  When rapidly creating new folders (e.g., deeply nested path of folders), events other than `CREATE` might not be emitted. To avoid this behavior, create the required folder structure in advance.
</Note>

<CodeGroup>
  ```js JavaScript & TypeScript highlight={13,17} theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
  import { Sandbox, FilesystemEventType } from 'e2b'

  const sandbox = await Sandbox.create()
  const dirname = '/home/user'

  // Start watching directory for changes
  const handle = await sandbox.files.watchDir(dirname, async (event) => {
    console.log(event)
    if (event.type === FilesystemEventType.WRITE) {
      console.log(`wrote to file ${event.name}`)
    }
  }, {
    recursive: true
  })

  // Trigger file write event
  await sandbox.files.write(`${dirname}/my-folder/my-file`, 'hello')
  ```

  ```python Python highlight={7,9} theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
  from e2b import Sandbox, FilesystemEventType

  sandbox = Sandbox.create()
  dirname = '/home/user'

  # Watch directory for changes
  handle = sandbox.files.watch_dir(dirname, recursive=True)
  # Trigger file write event
  sandbox.files.write(f"{dirname}/my-folder/my-file", "hello")

  # Retrieve the latest new events since the last `get_new_events()` call
  events = handle.get_new_events()
  for event in events:
    print(event)
    if event.type == FilesystemEventType.WRITE:
      print(f"wrote to file {event.name}")
  ```
</CodeGroup>

## Including entry information

You can include information about the affected file or directory in each event using the parameter `includeEntry` in JavaScript and `include_entry` in Python.
When enabled, each event carries the entry's information — such as its path, type, and size — in the `entry` field.

<Note>
  Entry information may be unset for remove events since the path no longer exists.
  Including entry information requires templates with envd version `v0.6.3` or above — using the `includeEntry` / `include_entry` option on older sandboxes will throw an error.
</Note>

<CodeGroup>
  ```js JavaScript & TypeScript highlight={10} theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
  import { Sandbox } from 'e2b'

  const sandbox = await Sandbox.create()
  const dirname = '/home/user'

  // Start watching directory for changes
  const handle = await sandbox.files.watchDir(dirname, async (event) => {
    console.log(event.type, event.name, event.entry?.path, event.entry?.type)
  }, {
    includeEntry: true
  })

  // Trigger file write event
  await sandbox.files.write(`${dirname}/my-file`, 'hello')
  ```

  ```python Python highlight={7,14} theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
  from e2b import Sandbox

  sandbox = Sandbox.create()
  dirname = '/home/user'

  # Watch directory for changes
  handle = sandbox.files.watch_dir(dirname, include_entry=True)
  # Trigger file write event
  sandbox.files.write(f"{dirname}/my-file", "hello")

  # Retrieve the latest new events since the last `get_new_events()` call
  events = handle.get_new_events()
  for event in events:
    print(event.type, event.name, event.entry.path if event.entry else None)
  ```
</CodeGroup>

## Watching network filesystem mounts

By default, watching paths on network filesystem mounts (NFS, CIFS, SMB, FUSE) is rejected. You can explicitly opt in using the parameter `allowNetworkMounts` in JavaScript and `allow_network_mounts` in Python.

<Note>
  Events on network mounts may be unreliable or not delivered at all, which is why the explicit opt-in is required.

  Changes made by another client outside of the sandbox (for example, a different machine writing to the same network share) are **not** propagated to the watcher — only changes made from within the sandbox are detected.
</Note>

<Note>
  Watching network mounts requires templates with envd version `v0.6.4` or above — using the `allowNetworkMounts` / `allow_network_mounts` option on older sandboxes will throw an error.
</Note>

<CodeGroup>
  ```js JavaScript & TypeScript highlight={10} theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
  import { Sandbox } from 'e2b'

  const sandbox = await Sandbox.create()
  const dirname = '/mnt/nfs-share/my-dir'

  // Start watching a directory on a network mount for changes
  const handle = await sandbox.files.watchDir(dirname, async (event) => {
    console.log(event.type, event.name)
  }, {
    allowNetworkMounts: true
  })

  // Trigger file write event
  await sandbox.files.write(`${dirname}/my-file`, 'hello')
  ```

  ```python Python highlight={7,14} theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
  from e2b import Sandbox

  sandbox = Sandbox.create()
  dirname = '/mnt/nfs-share/my-dir'

  # Watch a directory on a network mount for changes
  handle = sandbox.files.watch_dir(dirname, allow_network_mounts=True)
  # Trigger file write event
  sandbox.files.write(f"{dirname}/my-file", "hello")

  # Retrieve the latest new events since the last `get_new_events()` call
  events = handle.get_new_events()
  for event in events:
    print(event.type, event.name)
  ```
</CodeGroup>