# Watch sandbox directory for changes - Documentation

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown is available with `Accept: text/markdown` and `.md` URL variants.

Source: /docs/guides/sandbox-filesystem-watch

# Watch sandbox directory for changes

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

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

JavaScript & TypeScript

Python

```
import { Sandbox, FilesystemEventType } from 'novita-sandbox/code-interpreter'

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

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

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

// Stop watching directory for changes
handle.stop()

await sandbox.kill()
```

```
from novita_sandbox.code_interpreter import Sandbox, FilesystemEventType

sandbox = Sandbox.create()
dirname = '/tmp'

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

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

# Stop watching directory for changes
handle.stop()

sandbox.kill()
```

##

[​](#recursive-watching)

Recursive Watching

You can set the `recursive` parameter to enable recursive watching.

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.

JavaScript & TypeScript

Python

```
import { Sandbox, FilesystemEventType } from 'novita-sandbox/code-interpreter'

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

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

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

// Stop watching directory for changes
handle.stop()

await sandbox.kill()
```

```
from novita_sandbox.code_interpreter import Sandbox, FilesystemEventType

sandbox = Sandbox.create()
dirname = '/tmp'

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

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

# Stop watching directory for changes
handle.stop()

sandbox.kill()
```

Last modified on June 4, 2026