Skip to main content
A watcher reports filesystem events in a directory inside the sandbox: a file or directory is created, written, removed, renamed, or has its permissions changed. The Node.js SDK and the Python async SDK call a callback for each event. The Python sync SDK returns the events when polled. All three return a handle that is stopped with stop().
Install the SDK, or the CLI for ppio commands, and set the PPIO_API_KEY and PPIO_DOMAIN environment variables before running these examples. See Quickstart and Install and authenticate.

Event object and event types

Each event is a FilesystemEvent with two fields.
string
Relative path to the filesystem object.
FilesystemEventType
The kind of filesystem operation.
The type is one of the FilesystemEventType values.
FilesystemEventType
Value chmod. Object permissions were changed.
FilesystemEventType
Value create. Object was created.
FilesystemEventType
Value remove. Object was removed.
FilesystemEventType
Value rename. Object was renamed.
FilesystemEventType
Value write. Object was written to.

Watch a directory

watchDir(path, onEvent, opts?) starts watching and calls onEvent for each event. It returns a WatchHandle; call stop() to stop watching.
string
Directory to watch.
(event: FilesystemEvent) => void
Called for each event.
object
Optional. Options that control the watch.
Node.js
Recursive watching (recursive=True) requires an up-to-date template. On an older template, the SDK raises a template error that asks for a rebuild. Rebuild the template with ppio template build. See Errors.
Last modified on November 19, 2026