Skip to main content
Use sandbox.files.watch_dir() to receive real-time notifications when files are created, modified, or deleted.

Basic Usage

from moru import Sandbox

sandbox = Sandbox.create()

# Start watching a directory
handle = sandbox.files.watch_dir("/home/user/watched")

# Process events
for event in handle.events():
    print(f"Event: {event.type} - {event.name}")

# In another thread/process, make changes
# sandbox.files.write("/home/user/watched/new.txt", "Hello")

Event Types

Event TypeDescription
CREATEFile or directory was created
WRITE / MODIFYFile was modified
REMOVE / DELETEFile or directory was deleted
RENAMEFile or directory was renamed
CHMODPermissions were changed

Event Information

Each event contains:
PropertyTypeDescription
namestringRelative path from watched directory
typestringEvent type (CREATE, WRITE, REMOVE, etc.)
for event in handle.events():
    if event.type == "CREATE":
        print(f"New file: {event.name}")
    elif event.type == "WRITE":
        print(f"Modified: {event.name}")
    elif event.type == "REMOVE":
        print(f"Deleted: {event.name}")

Recursive Watching

Watch a directory and all its subdirectories:
# Watch recursively
handle = sandbox.files.watch_dir("/home/user/project", recursive=True)

for event in handle.events():
    print(f"{event.type}: {event.name}")

Stop Watching

handle = sandbox.files.watch_dir("/home/user/watched")

# Stop watching after some condition
for event in handle.events():
    print(event.name)
    if event.name == "done.txt":
        handle.stop()
        break

Live Reload Example

Watch for file changes and reload an application:
import threading
from moru import Sandbox

sandbox = Sandbox.create()

# Start a web server in background
sandbox.commands.run("python3 -m http.server 8080", background=True)

def watch_and_reload():
    handle = sandbox.files.watch_dir("/home/user/app", recursive=True)
    for event in handle.events():
        if event.name.endswith(".py"):
            print(f"Reloading due to: {event.name}")
            sandbox.commands.run("pkill -HUP python3")

thread = threading.Thread(target=watch_and_reload, daemon=True)
thread.start()

# Make changes and see reloads
sandbox.files.write("/home/user/app/main.py", "print('updated')")

File Sync Example

Sync files from sandbox to local machine:
import os
from moru import Sandbox

sandbox = Sandbox.create()
local_dir = "./synced_files"
os.makedirs(local_dir, exist_ok=True)

def sync_handler():
    handle = sandbox.files.watch_dir("/home/user/output", recursive=True)
    for event in handle.events():
        if event.type == "CREATE" or event.type == "WRITE":
            # Download the file
            remote_path = f"/home/user/output/{event.name}"
            local_path = os.path.join(local_dir, event.name)

            content = sandbox.files.read(remote_path, format="bytes")

            os.makedirs(os.path.dirname(local_path), exist_ok=True)
            with open(local_path, "wb") as f:
                f.write(content)

            print(f"Synced: {event.name}")

# Run sync in background thread
import threading
thread = threading.Thread(target=sync_handler, daemon=True)
thread.start()

User Context

Watch directories as a specific user:
# Watch as root to see all changes
handle = sandbox.files.watch_dir("/etc", user="root")

Options Reference

OptionTypeDefaultDescription
recursivebooleanfalseWatch subdirectories
userstring"user"User context
request_timeout / requestTimeoutMsnumber-Operation timeout

Next Steps