Watch a sandbox directory for create, write, remove, rename and chmod events with Node.js callbacks, Python async callbacks or Python sync polling.
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
Node.js
Python async
Python sync
watchDir(path, onEvent, opts?) starts watching and calls onEvent for each event. It returns a WatchHandle; call stop() to stop watching.
The Python async SDK uses a callback model: pass an on_event callback to watch_dir, which returns an AsyncWatchHandle. Stop it with await handle.stop().
The Python sync SDK uses a polling model: watch_dir(path, recursive=False) returns a WatchHandle, and get_new_events() returns the events that occurred since the last call. Stop it with stop().
str
Directory to watch.
str
Optional. Run the operation as this user.
float
Optional. Request timeout in seconds.
bool
default:"False"
Watch subdirectories too.
Python
import timefrom ppio_sandbox import PPIOppio = PPIO()sandbox = ppio.code_interpreter.create()watcher = sandbox.files.watch_dir('/tmp', recursive=True)try: for _ in range(10): events = watcher.get_new_events() for e in events: print(f'[{e.type.value}] {e.name}') time.sleep(1)except KeyboardInterrupt: passfinally: watcher.stop() sandbox.kill()
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
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"PPIO Docs","description":"Documentation for PPIO Model API and Agent Sandbox.","colors":{"primary":"#1161FE","light":"#4A85FE","dark":"#0B4BCC"},"logo":{"light":"https://mintcdn.com/ppio-global/ieVR5YoiewhhVFUV/logo/light-pulse.svg?fit=max\u0026auto=format\u0026n=ieVR5YoiewhhVFUV\u0026q=85\u0026s=213bd5e8edeee61418d3f42c9f98ef95","dark":"https://mintcdn.com/ppio-global/ieVR5YoiewhhVFUV/logo/dark-pulse.svg?fit=max\u0026auto=format\u0026n=ieVR5YoiewhhVFUV\u0026q=85\u0026s=cc626e1685c6d5dd7d1b03283d33beae","href":"https://ppio.ai"},"favicon":"https://mintcdn.com/ppio-global/wV6TQBGwRAbWQaCG/favicon.svg?fit=max\u0026auto=format\u0026n=wV6TQBGwRAbWQaCG\u0026q=85\u0026s=92d67fca71a07c0498760dea0256a1d3","navbar":{"primary":{"type":"button","label":"Console","href":"https://console.ppio.ai"}},"footer":{"links":[{"header":"Resources","items":[{"label":"Status","href":"https://status.ppio.ai"}]},{"header":"Legal","items":[{"label":"Privacy Policy","href":"https://ppio.ai/legal/privacy-policy"},{"label":"Terms of Service","href":"https://ppio.ai/legal/terms-of-service"}]}]},"seo":{"metatags":{"og:site_name":"PPIO Docs","application-name":"PPIO Docs","apple-mobile-web-app-title":"PPIO Docs"},"organization":{"name":"PPIO","url":"https://ppio.ai"},"indexing":"all"},"integrations":{"posthog":{"apiKey":"phc_u87cPcxgCRZ9agjeewC6y8pawGD7zg3kWJciAR828oVg","sessionRecording":false}},"contextual":{"options":["copy","view","mcp","vscode"],"display":"header"},"metadata":{"timestamp":true},"variables":{"modelApiBaseUrl":"https://api.ppio.com/openai","anthropicBaseUrl":"https://api.ppio.com/anthropic","exampleModel":"deepseek/deepseek-v4-pro"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"ppio-global","hasAudioNarration":false,"actualSubdomain":"ppio-global","customDomains":[],"gitSource":{"type":"github","owner":"ppio","repo":"ppio-global-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":"","_id":"6af6c9c2f3f7496a4c5f9e9d"},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6afeaa2d76078bd9e4dc95a0","clientVersion":"0.0.4227","searchFilterCounts":[{"language":"default","tag":"Documentation","count":43},{"language":"default","tag":"Agent Sandbox","count":39},{"language":"default","tag":"Sandboxes","count":11},{"language":"default","tag":"Filesystem","count":7},{"language":"default","tag":"CLI","count":4},{"language":"default","tag":"Templates","count":4},{"language":"default","tag":"Tools","count":3},{"language":"default","tag":"Get started","count":2},{"language":"default","tag":"Run code","count":2},{"language":"default","tag":"Networking","count":2}],"searchSettings":{"maxResults":5,"showContentSnippets":true}},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"global.css","content":"@media (min-width: 1024px){html:root{--topbar-tabs-height: 0rem}html:root [data-layout-item=\"side-panel\"]{top:calc(6.5rem + var(--banner-height, 0px));height:calc(100vh - 6.5rem - var(--banner-height, 0px))}#assistant-entry{display:none}#navbar div:has(>.nav-tabs){position:absolute;top:0;left:50%;transform:translateX(-50%);height:4rem;padding:0;pointer-events:none}#navbar .nav-tabs{display:grid;grid-auto-flow:column;grid-auto-columns:1fr;gap:0.5rem;height:100%;pointer-events:auto}#navbar .nav-tabs-item{justify-content:center;height:100%;padding:0 1.25rem;font-size:0.875rem;line-height:1.25rem;font-weight:500;letter-spacing:-0.01em;white-space:nowrap;color:rgb(var(--gray-600));text-shadow:none;transition:color 150ms}#navbar .nav-tabs-item:not([data-active]):hover{color:rgb(var(--gray-900))}#navbar .nav-tabs-item[data-active]{color:rgb(var(--primary))}#navbar .nav-tabs-item>div.absolute{display:block;height:2px;background-color:transparent;transition:background-color 150ms}#navbar .nav-tabs-item:not([data-active]):hover>div.absolute{background-color:rgb(var(--gray-950) / 0.12)}#navbar .nav-tabs-item[data-active]>div.absolute{background-color:rgb(var(--primary))}html.dark #navbar .nav-tabs-item{color:rgb(var(--gray-400))}html.dark #navbar .nav-tabs-item:not([data-active]):hover{color:rgb(var(--gray-200))}html.dark #navbar .nav-tabs-item:not([data-active]):hover>div.absolute{background-color:rgb(255 255 255 / 0.15)}html.dark #navbar .nav-tabs-item[data-active]{color:rgb(var(--primary-light))}html.dark #navbar .nav-tabs-item[data-active]>div.absolute{background-color:rgb(var(--primary-light))}#navbar div:has(>[data-layout-item=\"search-entry\"]){flex:0 0 auto}#navbar div:has(>[data-layout-item=\"search-entry\"])+div{flex:0 0 auto}#navbar [data-layout-item=\"search-entry\"]{width:270px}}@media (min-width: 1024px) and (max-width: 1439.98px){#navbar [data-layout-item=\"search-entry\"]{width:auto;aspect-ratio:1;padding:0;justify-content:center}#navbar [data-layout-item=\"search-entry\"] [data-search-item=\"trigger-label\"],#navbar [data-layout-item=\"search-entry\"] [data-search-item=\"trigger-hint\"]{display:none}}:root{--nv-toc-band-color: var(--primary)}html.dark{--nv-toc-band-color: var(--primary-light)}#table-of-contents [data-layout-item=\"toc-item\"]>[data-layout-item=\"toc-item-link\"]{--toc-padding-left: calc(var(--toc-depth, 0) * 1rem + 0.5rem)}html[data-nv-toc-band] #table-of-contents [data-layout-item=\"toc-item-link\"]{transition-property:color, background-color, border-color, outline-color, text-decoration-color, fill, stroke;transition-duration:150ms;transition-timing-function:cubic-bezier(0.4, 0, 0.2, 1)}html[data-nv-toc-band] #table-of-contents[data-look=\"default\"] [data-layout-item=\"toc-item\"][data-active]>[data-layout-item=\"toc-item-link\"]:not([data-nv-in-view]){color:rgb(var(--gray-600))}html[data-nv-toc-band] #table-of-contents[data-look=\"default\"] [data-layout-item=\"toc-item\"] [data-layout-item=\"toc-item\"][data-active]>[data-layout-item=\"toc-item-link\"]:not([data-nv-in-view]){color:rgb(var(--gray-500))}html.dark[data-nv-toc-band] #table-of-contents[data-look=\"default\"] [data-layout-item=\"toc-item\"][data-active]>[data-layout-item=\"toc-item-link\"]:not([data-nv-in-view]),html.dark[data-nv-toc-band] #table-of-contents[data-look=\"default\"] [data-layout-item=\"toc-item\"] [data-layout-item=\"toc-item\"][data-active]>[data-layout-item=\"toc-item-link\"]:not([data-nv-in-view]){color:rgb(var(--gray-400))}html[data-nv-toc-band] #table-of-contents[data-look=\"default\"] [data-layout-item=\"toc-item\"][data-active]>[data-layout-item=\"toc-item-link\"]{text-shadow:none}html[data-nv-toc-band] #table-of-contents[data-look=\"default\"] [data-layout-item=\"toc-item\"][data-active]>[data-layout-item=\"toc-item-link\"]:not([data-nv-in-view]):hover,html[data-nv-toc-band] #table-of-contents[data-look=\"default\"] [data-layout-item=\"toc-item\"] [data-layout-item=\"toc-item\"][data-active]>[data-layout-item=\"toc-item-link\"]:not([data-nv-in-view]):hover{color:rgb(var(--gray-900))}html.dark[data-nv-toc-band] #table-of-contents[data-look=\"default\"] [data-layout-item=\"toc-item\"][data-active]>[data-layout-item=\"toc-item-link\"]:not([data-nv-in-view]):hover,html.dark[data-nv-toc-band] #table-of-contents[data-look=\"default\"] [data-layout-item=\"toc-item\"] [data-layout-item=\"toc-item\"][data-active]>[data-layout-item=\"toc-item-link\"]:not([data-nv-in-view]):hover{color:rgb(var(--gray-300))}#table-of-contents [data-layout-item=\"toc-item-link\"][data-nv-in-view]{color:rgb(var(--nv-toc-band-color))}#table-of-contents nav{position:relative;isolation:isolate}.nv-toc-band{position:absolute;inset:0;z-index:-1;pointer-events:none;background:linear-gradient(to right, rgb(var(--nv-toc-band-color) / 0.1), transparent);clip-path:inset(0 0 100%)}.nv-toc-band[data-ready]{transition:clip-path 300ms cubic-bezier(0, 0, 0.2, 1)}@media (prefers-reduced-motion: reduce){html[data-nv-toc-band] #table-of-contents [data-layout-item=\"toc-item-link\"]{transition-property:color, background-color, border-color, outline-color, text-decoration-color, fill, stroke!important;transition-duration:150ms!important;transition-timing-function:cubic-bezier(0.4, 0, 0.2, 1)!important}}html[data-nv-sidebar-glide] #navigation-items{position:relative;isolation:isolate}html[data-nv-sidebar-glide] .nv-sidebar-glide{position:absolute;top:0;left:0;z-index:-1;box-sizing:border-box;padding:2px 0;border-radius:8px;background-color:rgb(209 209 209 / 0.3012);background-clip:content-box;opacity:0;pointer-events:none;transition:opacity 200ms cubic-bezier(0.22, 1, 0.36, 1)}html.dark[data-nv-sidebar-glide] .nv-sidebar-glide{background-color:rgb(104 104 104 / 0.1812)}html[data-nv-sidebar-glide] #navigation-items :is(a[href],button,[role=\"button\"]):not(.nav-anchor):not([aria-current=\"page\"]):hover{background-color:transparent}html[data-nv-sidebar-glide] #navigation-items :is(a[href],button,[role=\"button\"]):not(.nav-anchor){transition-property:color, background-color, border-color, outline-color, text-decoration-color, fill, stroke;transition-duration:150ms;transition-timing-function:cubic-bezier(0.4, 0, 0.2, 1)}@media (prefers-reduced-motion: no-preference){html[data-nv-sidebar-glide] .nv-sidebar-glide{transition-property:translate, width, height, opacity}}@media (prefers-reduced-motion: reduce){html[data-nv-sidebar-glide] .nv-sidebar-glide{transition:opacity 200ms cubic-bezier(0.22, 1, 0.36, 1)!important}html[data-nv-sidebar-glide] #navigation-items :is(a[href],button,[role=\"button\"]):not(.nav-anchor){transition-property:color, background-color, border-color, outline-color, text-decoration-color, fill, stroke!important;transition-duration:150ms!important;transition-timing-function:cubic-bezier(0.4, 0, 0.2, 1)!important}}#footer button[aria-label^=\"Switch to\"]{display:none}@media (min-width: 1024px){.advanced-footer>div{display:grid;grid-template-columns:auto minmax(0, 1fr);column-gap:2rem;row-gap:0}.advanced-footer>div>div:has(img.nav-logo),.advanced-footer>div>div:has(a[href*=\"utm_campaign=poweredBy\"]){display:contents}.advanced-footer>div>div:has(img.nav-logo)>div:has(img.nav-logo){grid-area:1 / 1}.advanced-footer>div>div:has(img.nav-logo)>div:not(:has(img.nav-logo)){grid-area:1 / 2 / 3 / 3}.advanced-footer>div>div:has(a[href*=\"utm_campaign=poweredBy\"])>div:has(a[href*=\"utm_campaign=poweredBy\"]){grid-area:2 / 1;align-self:end}.advanced-footer>div>div:empty,.advanced-footer>div>div:has(a[href*=\"utm_campaign=poweredBy\"])>div:not(:has(a[href*=\"utm_campaign=poweredBy\"])){display:none}}#pagination{display:grid;grid-template-columns:repeat(2, minmax(0, 1fr));gap:0.75rem;container-type:inline-size}#pagination :is([data-component-part=\"pagination-prev\"],[data-component-part=\"pagination-next\"]){display:grid;align-items:center;column-gap:0.375rem;row-gap:0.25rem;margin:0;padding:1rem;border:1px solid rgb(var(--gray-950) / 0.1);border-radius:1rem;font-size:0.875rem;line-height:1.25rem;transition-property:border-color, box-shadow;transition-duration:150ms;transition-timing-function:cubic-bezier(0.4, 0, 0.2, 1)}#pagination [data-component-part=\"pagination-prev\"]{grid-template-columns:auto minmax(0, 1fr)}#pagination [data-component-part=\"pagination-prev\"]>svg{grid-area:1 / 1}#pagination [data-component-part=\"pagination-prev\"]::before{content:\"Previous Page\";grid-area:1 / 2}#pagination [data-component-part=\"pagination-next\"]{grid-column:2;grid-template-columns:minmax(0, 1fr) auto;justify-items:end;text-align:end}#pagination [data-component-part=\"pagination-next\"]::before{content:\"Next Page\";grid-area:1 / 1}#pagination [data-component-part=\"pagination-next\"]>svg{grid-area:1 / 2}#pagination :is([data-component-part=\"pagination-prev\"],[data-component-part=\"pagination-next\"])::before,#pagination :is([data-component-part=\"pagination-prev\"],[data-component-part=\"pagination-next\"])>svg{margin:0;font-weight:400;color:rgb(var(--gray-500))}#pagination [data-component-part=\"pagination-title\"]{grid-area:2 / 1 / 3 / -1;font-weight:500;color:rgb(var(--gray-900))}#pagination :is([data-component-part=\"pagination-prev\"],[data-component-part=\"pagination-next\"]):hover{border-color:rgb(var(--primary));box-shadow:inset 0 0 0 1px rgb(var(--primary))}html.dark #pagination :is([data-component-part=\"pagination-prev\"],[data-component-part=\"pagination-next\"]){border-color:rgb(255 255 255 / 0.1)}html.dark #pagination :is([data-component-part=\"pagination-prev\"],[data-component-part=\"pagination-next\"])::before,html.dark #pagination :is([data-component-part=\"pagination-prev\"],[data-component-part=\"pagination-next\"])>svg{color:rgb(var(--gray-400))}html.dark #pagination [data-component-part=\"pagination-title\"]{color:rgb(var(--gray-100))}html.dark #pagination :is([data-component-part=\"pagination-prev\"],[data-component-part=\"pagination-next\"]):hover{border-color:rgb(var(--primary-light));box-shadow:inset 0 0 0 1px rgb(var(--primary-light))}@container (max-width: 28rem){#pagination :is([data-component-part=\"pagination-prev\"],[data-component-part=\"pagination-next\"]){grid-column:1 / -1}}:root{--nv-heading-flash: var(--primary)}html.dark{--nv-heading-flash: var(--primary-light)}@keyframes nv-heading-flash{from{background-color:rgb(var(--nv-heading-flash) / 0.12);box-shadow:0 0 0 0.375rem rgb(var(--nv-heading-flash) / 0.12)}to{background-color:transparent;box-shadow:0 0 0 0.375rem transparent}}#content :is(h1,h2,h3,h4,h5,h6):target{border-radius:0.375rem;animation:nv-heading-flash 1.2s ease-out}@media (prefers-reduced-motion: reduce){#content :is(h1,h2,h3,h4,h5,h6):target{animation:none}}#content .anchor-link[data-ppio-copied]{opacity:1}#content .anchor-link[data-ppio-copied]::after{background-color:rgb(var(--primary));-webkit-mask-image:url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M20 6 9 17l-5-5'/%3E%3C/svg%3E\");mask-image:url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M20 6 9 17l-5-5'/%3E%3C/svg%3E\")}html.dark #content .anchor-link[data-ppio-copied]::after{background-color:rgb(var(--primary-light))}.nv-heading-copy-bubble{position:absolute;bottom:calc(100% + 2px);left:12px;z-index:1;transform:translateX(-50%);padding:4px 8px;border-radius:6px;font-size:12px;line-height:16px;white-space:nowrap;color:rgb(255 255 255);background-color:rgb(var(--gray-900));opacity:0;pointer-events:none;transition:opacity 150ms}.nv-heading-copy-bubble[data-shown]{opacity:1}html.dark .nv-heading-copy-bubble{color:rgb(var(--gray-900));background-color:rgb(var(--gray-100))}.nv-heading-copy-status{position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;border:0}.ppio-home{--ppio-home-fade: 150ms cubic-bezier(0.4, 0, 0.2, 1)}.ppio-home-hero{position:relative;isolation:isolate;background-color:#eef1fd;background-image:radial-gradient(55% 80% at 15% 0%, rgb(var(--primary) / 0.12), transparent 70%),\n radial-gradient(50% 75% at 85% 10%, rgb(139 92 246 / 0.1), transparent 70%),\n linear-gradient(to bottom, #eef1fd, #f3f5fe)}.ppio-home-hero::before{content:\"\";position:absolute;inset:0;z-index:-1;pointer-events:none;background-image:linear-gradient(to right, rgb(var(--primary) / 0.07) 1px, transparent 1px),\n linear-gradient(to bottom, rgb(var(--primary) / 0.07) 1px, transparent 1px);background-size:48px 48px;background-position:center top;-webkit-mask-image:radial-gradient(ellipse 60% 80% at 50% 0%, #000 30%, transparent 100%);mask-image:radial-gradient(ellipse 60% 80% at 50% 0%, #000 30%, transparent 100%)}html.dark .ppio-home-hero{background-color:#0b1229;background-image:radial-gradient(55% 80% at 15% 0%, rgb(var(--primary) / 0.22), transparent 70%),\n radial-gradient(50% 75% at 85% 10%, rgb(139 92 246 / 0.16), transparent 70%),\n linear-gradient(to bottom, #0c1530, #0a0f20)}html.dark .ppio-home-hero::before{background-image:linear-gradient(to right, rgb(255 255 255 / 0.05) 1px, transparent 1px),\n linear-gradient(to bottom, rgb(255 255 255 / 0.05) 1px, transparent 1px)}.ppio-home-external{position:absolute;top:50%;left:100%;margin-left:0.375rem;transform:translateY(-50%);background-color:rgb(var(--gray-500));transition:background-color var(--ppio-home-fade)}@media (hover: hover){.ppio-home-card:hover{border-color:rgb(var(--primary));box-shadow:0 12px 28px -16px rgb(var(--primary) / 0.4)}html.dark .ppio-home-card:hover{border-color:rgb(var(--primary-light))}.ppio-home-card:hover .ppio-home-external{background-color:rgb(var(--primary))}html.dark .ppio-home-card:hover .ppio-home-external{background-color:rgb(var(--primary-light))}}@media (hover: hover) and (prefers-reduced-motion: no-preference){.ppio-home-card{transition:transform var(--ppio-home-fade), border-color var(--ppio-home-fade), box-shadow var(--ppio-home-fade)}.ppio-home-card:hover{transform:translateY(-2px)}}.ppio-home-links{--ppio-home-links-gap: 0.25rem;--ppio-home-link-text: rgb(var(--gray-700));--ppio-home-link-accent: rgb(var(--primary));--ppio-home-link-fill: rgb(var(--primary) / 0.06);--ppio-home-link-edge: rgb(var(--primary) / 0.2);display:grid;grid-row:span 2;grid-template-columns:repeat(2, minmax(0, 1fr));grid-template-rows:subgrid;gap:var(--ppio-home-links-gap);margin:1.25rem -0.5rem -0.5rem;padding-top:0.5rem;border-top:1px solid rgb(var(--gray-950) / 0.1);font-size:0.8125rem;line-height:1.125rem}html.dark .ppio-home-links{--ppio-home-link-text: rgb(var(--gray-400));--ppio-home-link-accent: rgb(var(--primary-light));--ppio-home-link-fill: rgb(var(--primary-light) / 0.1);--ppio-home-link-edge: rgb(var(--primary-light) / 0.25);border-top-color:rgb(255 255 255 / 0.1)}.ppio-home-links>li{display:flex}.ppio-home-links>li:last-child:nth-child(odd){grid-column:1 / -1;justify-self:center;width:calc(50% - var(--ppio-home-links-gap) / 2)}.ppio-home-link{display:flex;flex:1;flex-direction:column;align-items:center;gap:0.5rem;padding:0.75rem 0.5rem;border:1px solid transparent;border-radius:0.5rem;font-weight:500;text-align:center;color:var(--ppio-home-link-text);transition:color var(--ppio-home-fade), background-color var(--ppio-home-fade), border-color var(--ppio-home-fade)}.ppio-home-link>.icon{width:1.125rem!important;height:1.125rem!important;background-color:var(--ppio-home-link-accent)}.ppio-home-link:is(:focus-visible,:active){border-color:var(--ppio-home-link-edge);background-color:var(--ppio-home-link-fill);color:var(--ppio-home-link-accent)}@media (hover: hover){.ppio-home-link:hover{border-color:var(--ppio-home-link-edge);background-color:var(--ppio-home-link-fill);color:var(--ppio-home-link-accent)}}@media (prefers-reduced-motion: reduce){.ppio-home-card{transition:border-color var(--ppio-home-fade), box-shadow var(--ppio-home-fade)!important}.ppio-home-external{transition:background-color var(--ppio-home-fade)!important}.ppio-home-link{transition:color var(--ppio-home-fade), background-color var(--ppio-home-fade), border-color var(--ppio-home-fade)!important}}.ppio-home a:focus-visible{outline:2px solid rgb(var(--primary));outline-offset:2px}html.dark .ppio-home a:focus-visible{outline-color:rgb(var(--primary-light))}"}]}
{"page":{"pagePath":"sandbox/filesystem/watch","slug":"/sandbox/filesystem/watch","pageMetadata":{"title":"Watch a directory for changes","sidebarTitle":"Watch changes","description":"Watch a sandbox directory for create, write, remove, rename and chmod events with Node.js callbacks, Python async callbacks or Python sync polling.","keywords":["sandbox","filesystem","watch","filesystem events","watch_dir"],"href":"/sandbox/filesystem/watch"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Watch a sandbox directory for create, write, remove, rename and chmod events with Node.js callbacks, Python async callbacks or Python sync polling.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,..._provideComponents(),...props.components},{CodeBlock,Expandable,Heading,Info,ParamField,ResponseField,Tab,Tabs}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Expandable)_missingMdxReference(`Expandable`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Info)_missingMdxReference(`Info`,true);if(!ParamField)_missingMdxReference(`ParamField`,true);if(!ResponseField)_missingMdxReference(`ResponseField`,true);if(!Tab)_missingMdxReference(`Tab`,true);if(!Tabs)_missingMdxReference(`Tabs`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`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 `,_jsx(_components.code,{children:`stop()`}),`.`]}),`\n`,_jsxs(Info,{children:[`Install the SDK, or the CLI for `,_jsx(_components.code,{children:`ppio`}),` commands, and set the `,_jsx(_components.code,{children:`PPIO_API_KEY`}),` and `,_jsx(_components.code,{children:`PPIO_DOMAIN`}),` environment variables before running these examples. See `,_jsx(_components.a,{href:`/sandbox/quickstart`,children:`Quickstart`}),` and `,_jsx(_components.a,{href:`/sandbox/cli/install`,children:`Install and authenticate`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`event-object-and-event-types`,children:`Event object and event types`}),`\n`,_jsxs(_components.p,{children:[`Each event is a `,_jsx(_components.code,{children:`FilesystemEvent`}),` with two fields.`]}),`\n`,_jsx(ResponseField,{name:`name`,type:`string`,id:`param-name`,children:_jsx(_components.p,{children:`Relative path to the filesystem object.`})}),`\n`,_jsx(ResponseField,{name:`type`,type:`FilesystemEventType`,id:`param-type`,children:_jsx(_components.p,{children:`The kind of filesystem operation.`})}),`\n`,_jsxs(_components.p,{children:[`The `,_jsx(_components.code,{children:`type`}),` is one of the `,_jsx(_components.code,{children:`FilesystemEventType`}),` values.`]}),`\n`,_jsx(ResponseField,{name:`FilesystemEventType.CHMOD`,type:`FilesystemEventType`,id:`param-filesystem-event-type-chmod`,children:_jsxs(_components.p,{children:[`Value `,_jsx(_components.code,{children:`chmod`}),`. Object permissions were changed.`]})}),`\n`,_jsx(ResponseField,{name:`FilesystemEventType.CREATE`,type:`FilesystemEventType`,id:`param-filesystem-event-type-create`,children:_jsxs(_components.p,{children:[`Value `,_jsx(_components.code,{children:`create`}),`. Object was created.`]})}),`\n`,_jsx(ResponseField,{name:`FilesystemEventType.REMOVE`,type:`FilesystemEventType`,id:`param-filesystem-event-type-remove`,children:_jsxs(_components.p,{children:[`Value `,_jsx(_components.code,{children:`remove`}),`. Object was removed.`]})}),`\n`,_jsx(ResponseField,{name:`FilesystemEventType.RENAME`,type:`FilesystemEventType`,id:`param-filesystem-event-type-rename`,children:_jsxs(_components.p,{children:[`Value `,_jsx(_components.code,{children:`rename`}),`. Object was renamed.`]})}),`\n`,_jsx(ResponseField,{name:`FilesystemEventType.WRITE`,type:`FilesystemEventType`,id:`param-filesystem-event-type-write`,children:_jsxs(_components.p,{children:[`Value `,_jsx(_components.code,{children:`write`}),`. Object was written to.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`watch-a-directory`,children:`Watch a directory`}),`\n`,_jsxs(Tabs,{children:[_jsxs(Tab,{title:`Node.js`,id:`node-js`,children:[_jsxs(_components.p,{children:[_jsx(_components.code,{children:`watchDir(path, onEvent, opts?)`}),` starts watching and calls `,_jsx(_components.code,{children:`onEvent`}),` for each event. It returns a `,_jsx(_components.code,{children:`WatchHandle`}),`; call `,_jsx(_components.code,{children:`stop()`}),` to stop watching.`]}),_jsx(ParamField,{body:`path`,type:`string`,id:`param-path`,children:`Directory to watch.`}),_jsx(ParamField,{body:`onEvent`,type:`(event: FilesystemEvent) => void`,id:`param-on-event`,children:`Called for each event.`}),_jsxs(ParamField,{body:`opts`,type:`object`,id:`param-opts`,children:[_jsx(_components.p,{children:`Optional. Options that control the watch.`}),_jsxs(Expandable,{title:`opts`,defaultOpen:true,children:[_jsx(ParamField,{body:`recursive`,type:`boolean`,default:`false`,id:`param-recursive`,children:`Watch subdirectories too.`}),_jsxs(ParamField,{body:`timeoutMs`,type:`number`,default:`60000`,id:`param-timeout-ms`,children:[`Watch timeout in milliseconds; `,_jsx(_components.code,{children:`0`}),` disables it.`]}),_jsx(ParamField,{body:`onExit`,type:`(err?: Error) => void`,id:`param-on-exit`,children:`Called when watching stops.`}),_jsx(ParamField,{body:`user`,type:`string`,id:`param-user`,children:`Run the operation as this user.`})]})]}),_jsx(CodeBlock,{filename:`Node.js`,numberOfLines:`18`,language:`javascript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`javascript`,children:_jsxs(_components.code,{language:`javascript`,numberOfLines:`18`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`// index.mts`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` { `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`PPIO`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` } `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`from`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'ppio-sandbox'`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` ppio`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` new`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` PPIO`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`()`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` sandbox`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` ppio`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`codeInterpreter`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`create`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`()`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` handle`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` sandbox`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`files`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`watchDir`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '/tmp'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:`event`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`=>`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` console`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`log`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"`[\"}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:\"${\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`event`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`type`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`] `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:\"${\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`event`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`name`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"`\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` { `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`recursive:`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` true`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`// ... trigger some file changes ...`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` handle`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`stop`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`()`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` sandbox`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`kill`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`()`})]}),`\n`]})})})]}),_jsxs(Tab,{title:`Python async`,id:`python-async`,children:[_jsxs(_components.p,{children:[`The Python async SDK uses a callback model: pass an `,_jsx(_components.code,{children:`on_event`}),` callback to `,_jsx(_components.code,{children:`watch_dir`}),`, which returns an `,_jsx(_components.code,{children:`AsyncWatchHandle`}),`. Stop it with `,_jsx(_components.code,{children:`await handle.stop()`}),`.`]}),_jsx(CodeBlock,{filename:`Python`,numberOfLines:`17`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`17`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` asyncio`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`from`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ppio_sandbox.code_interpreter `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` AsyncSandbox`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`async`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` def`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` main`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`():`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` sandbox `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` AsyncSandbox.create()`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` def`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` on_event`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`e`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#DCDCAA`},children:` print`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'[`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`{`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`e.type.value`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`] `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`{`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`e.name`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` handle `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` sandbox.files.watch_dir(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'/tmp'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:`on_event`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`on_event, `}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:`recursive`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`True`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # ... trigger some file changes ...`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` handle.stop()`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` sandbox.kill()`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`asyncio.run(main())`})}),`\n`]})})})]}),_jsxs(Tab,{title:`Python sync`,id:`python-sync`,children:[_jsxs(_components.p,{children:[`The Python sync SDK uses a polling model: `,_jsx(_components.code,{children:`watch_dir(path, recursive=False)`}),` returns a `,_jsx(_components.code,{children:`WatchHandle`}),`, and `,_jsx(_components.code,{children:`get_new_events()`}),` returns the events that occurred since the last call. Stop it with `,_jsx(_components.code,{children:`stop()`}),`.`]}),_jsx(ParamField,{body:`path`,type:`str`,id:`param-path-1`,children:`Directory to watch.`}),_jsx(ParamField,{body:`user`,type:`str`,id:`param-user-1`,children:`Optional. Run the operation as this user.`}),_jsx(ParamField,{body:`request_timeout`,type:`float`,id:`param-request-timeout`,children:`Optional. Request timeout in seconds.`}),_jsx(ParamField,{body:`recursive`,type:`bool`,default:`False`,id:`param-recursive-1`,children:`Watch subdirectories too.`}),_jsx(CodeBlock,{filename:`Python`,numberOfLines:`19`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`19`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` time`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`from`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ppio_sandbox `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#D4D4D4`},children:` PPIO`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`ppio `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` PPIO()`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`sandbox `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ppio.code_interpreter.create()`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`watcher `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` sandbox.files.watch_dir(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'/tmp'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:`recursive`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`True`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`try`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` for`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` _ `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`in`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#DCDCAA`},children:` range`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`10`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` events `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` watcher.get_new_events()`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` for`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` e `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`in`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` events:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#DCDCAA`},children:` print`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'[`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`{`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`e.type.value`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`] `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`{`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`e.name`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` time.sleep(`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`1`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`except`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4EC9B0`},children:` KeyboardInterrupt`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` pass`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`finally`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` watcher.stop()`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` sandbox.kill()`})}),`\n`]})})})]})]}),`\n`,_jsxs(Info,{children:[`Recursive watching (`,_jsx(_components.code,{children:`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 `,_jsx(_components.code,{children:`ppio template build`}),`. See `,_jsx(_components.a,{href:`/sandbox/errors`,children:`Errors`}),`.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Watch a directory for changes","sidebarTitle":"Watch changes","description":"Watch a sandbox directory for create, write, remove, rename and chmod events with Node.js callbacks, Python async callbacks or Python sync polling.","keywords":["sandbox","filesystem","watch","filesystem events","watch_dir"],"href":"/sandbox/filesystem/watch"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Event object and event types","slug":"event-object-and-event-types","depth":2,"children":[]},{"title":"Watch a directory","slug":"watch-a-directory","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/ppio-global/4bb89b3ad5ecd5aa/heading-link-feedback.js","/_mintlify/custom/ppio-global/df467f00fa8cffe2/related-topics-new-tab.js","/_mintlify/custom/ppio-global/723c37d60c155011/sidebar-glide.js","/_mintlify/custom/ppio-global/608b56d8850b9175/toc-band.js"],"subdomain":"ppio-global","siteName":"PPIO Docs","title":"Watch a directory for changes - PPIO Docs","relatedPagesConfig":{"enabled":true,"limit":3,"mode":"automatic"},"navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-19T07:08:37.284Z","gitLastModified":"2026-11-19T07:08:10.000Z","originalFileLocation":"sandbox/filesystem/watch.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Watch a sandbox directory for create, write, remove, rename and chmod events with Node.js callbacks, Python async callbacks or Python sync polling.\">\u003cmeta data-mint-head name=\"application-name\" content=\"PPIO Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/ppio-global/i7am2RcGdmhjKsRJ/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/ppio-global/i7am2RcGdmhjKsRJ/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/ppio-global/i7am2RcGdmhjKsRJ/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/ppio-global/i7am2RcGdmhjKsRJ/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/ppio-global/i7am2RcGdmhjKsRJ/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/ppio-global/i7am2RcGdmhjKsRJ/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/ppio-global/i7am2RcGdmhjKsRJ/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/ppio-global/i7am2RcGdmhjKsRJ/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/ppio-global/i7am2RcGdmhjKsRJ/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Watch a directory for changes - PPIO Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Watch a sandbox directory for create, write, remove, rename and chmod events with Node.js callbacks, Python async callbacks or Python sync polling.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"PPIO Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://ppio-global.mintlify.app/sandbox/filesystem/watch\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://ppio-global.mintlify.site/_mintlify/api/og/v2?division=Filesystem\u0026amp;title=Watch+a+directory+for+changes\u0026amp;description=Watch+a+sandbox+directory+for+create%2C+write%2C+remove%2C+rename+and+chmod+events+with+Node.js+callbacks%2C+Python+async+callbacks+or+Python+sync+polling.\u0026amp;theme=0fff330243c422b9cc7ab4d2\u0026amp;signature=7e337a6edf9baedc87a5874bdca051b040c7224c2d9429055b6bc41944b5b799\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Watch a directory for changes - PPIO Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Watch a sandbox directory for create, write, remove, rename and chmod events with Node.js callbacks, Python async callbacks or Python sync polling.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://ppio-global.mintlify.site/_mintlify/api/og/v2?division=Filesystem\u0026amp;title=Watch+a+directory+for+changes\u0026amp;description=Watch+a+sandbox+directory+for+create%2C+write%2C+remove%2C+rename+and+chmod+events+with+Node.js+callbacks%2C+Python+async+callbacks+or+Python+sync+polling.\u0026amp;theme=0fff330243c422b9cc7ab4d2\u0026amp;signature=7e337a6edf9baedc87a5874bdca051b040c7224c2d9429055b6bc41944b5b799\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/ppio-global/i7am2RcGdmhjKsRJ/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"PPIO Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#1161FE\">\u003cmeta data-mint-head name=\"application-name\" content=\"PPIO Docs\">\u003clink data-mint-head rel=\"canonical\" href=\"https://ppio-global.mintlify.app/sandbox/filesystem/watch\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/sandbox/filesystem/watch.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://ppio.ai/#organization\",\"name\":\"PPIO\",\"url\":\"https://ppio.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/ppio-global/ieVR5YoiewhhVFUV/logo/light-pulse.svg?fit=max\u0026auto=format\u0026n=ieVR5YoiewhhVFUV\u0026q=85\u0026s=213bd5e8edeee61418d3f42c9f98ef95\"}},{\"@type\":\"WebSite\",\"@id\":\"https://ppio-global.mintlify.app#website\",\"name\":\"PPIO Docs\",\"url\":\"https://ppio-global.mintlify.app\",\"publisher\":{\"@id\":\"https://ppio.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://ppio-global.mintlify.app/sandbox/filesystem/watch#webpage\",\"url\":\"https://ppio-global.mintlify.app/sandbox/filesystem/watch\",\"name\":\"Watch a directory for changes\",\"description\":\"Watch a sandbox directory for create, write, remove, rename and chmod events with Node.js callbacks, Python async callbacks or Python sync polling.\",\"dateModified\":\"2026-11-19T07:08:10.000Z\",\"isPartOf\":{\"@id\":\"https://ppio-global.mintlify.app#website\"},\"breadcrumb\":{\"@id\":\"https://ppio-global.mintlify.app/sandbox/filesystem/watch#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://ppio-global.mintlify.app/sandbox/filesystem/watch#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Agent Sandbox\",\"item\":\"https://ppio-global.mintlify.app/sandbox/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Filesystem\",\"item\":\"https://ppio-global.mintlify.app/sandbox/filesystem/overview\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Watch a directory for changes\",\"item\":\"https://ppio-global.mintlify.app/sandbox/filesystem/watch\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://ppio-global.mintlify.app/sandbox/filesystem/watch#article\",\"headline\":\"Watch a directory for changes\",\"name\":\"Watch a directory for changes\",\"description\":\"Watch a sandbox directory for create, write, remove, rename and chmod events with Node.js callbacks, Python async callbacks or Python sync polling.\",\"url\":\"https://ppio-global.mintlify.app/sandbox/filesystem/watch\",\"mainEntityOfPage\":{\"@id\":\"https://ppio-global.mintlify.app/sandbox/filesystem/watch#webpage\"},\"dateModified\":\"2026-11-19T07:08:10.000Z\",\"keywords\":\"sandbox, filesystem, watch, filesystem events, watch_dir\",\"publisher\":{\"@id\":\"https://ppio.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://ppio-global.mintlify.app#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"PPIO Docs\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"PPIO\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/sandbox/filesystem/watch.md","siteName":"PPIO Docs","nav":{"global":null,"tabs":[{"tab":"Documentation","groups":[{"group":"Get started","pages":[{"title":"PPIO Model API and Agent Sandbox","sidebarTitle":"Home","mode":"custom","href":""},{"title":"Quickstart","href":"/quickstart"}]},{"group":"Model API","pages":[{"title":"Model API overview","href":"/model-api/overview"}]},{"group":"Agent Sandbox","pages":[{"title":"Agent Sandbox: secure cloud sandboxes for AI agents","sidebarTitle":"Overview","href":"/sandbox/overview"},{"title":"Create your first sandbox","sidebarTitle":"Quickstart","href":"/sandbox/quickstart"},{"title":"How Agent Sandbox billing works","sidebarTitle":"Billing","href":"/sandbox/billing"},{"title":"Agent Sandbox quotas and limits","sidebarTitle":"Quotas and limits","href":"/sandbox/quotas"},{"title":"Manage sandboxes in the PPIO console","sidebarTitle":"Console","href":"/sandbox/console"},{"group":"Sandboxes","pages":[{"title":"Sandbox lifecycle and states","sidebarTitle":"Lifecycle","href":"/sandbox/lifecycle"},{"title":"Create a sandbox","sidebarTitle":"Create","href":"/sandbox/create"},{"title":"Connect to a running sandbox","sidebarTitle":"Connect","href":"/sandbox/connect"},{"title":"List and filter sandboxes","sidebarTitle":"List","href":"/sandbox/list"},{"title":"Set or extend a sandbox timeout","sidebarTitle":"Timeout","href":"/sandbox/timeout"},{"title":"Configure an idle timeout","sidebarTitle":"Idle timeout","href":"/sandbox/idle-timeout"},{"title":"Pause and resume a sandbox","sidebarTitle":"Pause and resume","href":"/sandbox/pause-resume"},{"title":"Save and restore sandbox state with snapshots","sidebarTitle":"Snapshots","href":"/sandbox/snapshots"},{"title":"Kill a sandbox","sidebarTitle":"Kill","href":"/sandbox/kill"},{"title":"Monitor sandbox CPU, memory, and disk","sidebarTitle":"Metrics","href":"/sandbox/metrics"},{"title":"Query sandbox lifecycle events","sidebarTitle":"Events","href":"/sandbox/events"}]},{"group":"Run code","pages":[{"title":"Run commands in a sandbox","sidebarTitle":"Commands","href":"/sandbox/commands"},{"title":"Open an interactive terminal (PTY)","sidebarTitle":"Interactive terminal","href":"/sandbox/terminal"}]},{"group":"Filesystem","pages":[{"title":"Work with files in a sandbox","sidebarTitle":"Overview","href":"/sandbox/filesystem/overview"},{"title":"Read and write files","sidebarTitle":"Read and write","href":"/sandbox/filesystem/read-write"},{"title":"Get file and directory metadata","sidebarTitle":"Metadata","description":"Get the name, type, path, size, permissions, owner, group and modified time of a file or directory in a sandbox with get_info() or getInfo().","href":"/sandbox/filesystem/metadata"},{"title":"Watch a directory for changes","sidebarTitle":"Watch changes","href":"/sandbox/filesystem/watch"},{"title":"Upload files to a sandbox","sidebarTitle":"Upload","description":"Upload a single local file, a directory or several files to a sandbox with files.write(), or let a browser upload through a pre-signed URL.","href":"/sandbox/filesystem/upload"},{"title":"Download files from a sandbox","sidebarTitle":"Download","href":"/sandbox/filesystem/download"},{"title":"Mount an S3 bucket in a sandbox","sidebarTitle":"Mount S3","href":"/sandbox/filesystem/mount-s3"}]},{"group":"Networking","pages":[{"title":"Control internet access and expose ports","sidebarTitle":"Internet access","href":"/sandbox/internet-access"},{"title":"Secure access to sandbox services","sidebarTitle":"Secured access","href":"/sandbox/secured-access"}]},{"group":"Templates","pages":[{"title":"What is a sandbox template?","sidebarTitle":"Overview","href":"/sandbox/templates/overview"},{"title":"Build a template with the SDK","sidebarTitle":"Build with SDK","href":"/sandbox/templates/build"},{"title":"Build a template with the CLI","sidebarTitle":"Build with CLI","href":"/sandbox/templates/build-cli"},{"title":"List, tag, publish, and delete templates","sidebarTitle":"Manage","href":"/sandbox/templates/manage"}]},{"group":"Tools","pages":[{"title":"Use Git in a sandbox","sidebarTitle":"Git","href":"/sandbox/git"},{"title":"Run a desktop sandbox for computer use","sidebarTitle":"Computer use","href":"/sandbox/computer-use"},{"title":"Connect a sandbox to a VPN with OpenVPN","sidebarTitle":"OpenVPN","href":"/sandbox/openvpn"}]},{"group":"CLI","pages":[{"title":"Install and sign in to the PPIO CLI","sidebarTitle":"Install and authenticate","href":"/sandbox/cli/install"},{"title":"ppio sandbox connect","sidebarTitle":"ppio sandbox connect","href":"/sandbox/cli/connect"},{"title":"ppio sandbox exec","sidebarTitle":"ppio sandbox exec","href":"/sandbox/cli/exec"},{"title":"ppio sandbox network","sidebarTitle":"ppio sandbox network","href":"/sandbox/cli/network"}]},{"title":"Agent Sandbox errors","sidebarTitle":"Errors","href":"/sandbox/errors"}]},{"group":"Platform","pages":[{"title":"Console overview","href":"/platform/console"}]}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/api-reference/introduction"}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/changelog"}]}]},"basePath":"","title":"Watch a directory for changes - PPIO Docs","deploymentId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","buildId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","dynamics":[],"chunks":[]}