Overview

Notifications tell an agent when files or directories change in the virtual filesystem. For example, a teammate edits a report in connected storage, and your agent receives the report’s virtual path and what happened to it.

How it works

Your application receives a service notification or checks for changes.
It reports each change to Mirage with ws.notify().
The agent receives it through ws.events().

Your application connects the service’s notifications to Mirage. Subscribing with ws.events() alone does not start a file watcher or check the service.

Listen for changes

Here, ws is your workspace with a VFS connected at /data. This listens for changes anywhere under that path:

async for change in ws.events("/data"):
    print(f"Event: {change.kind.value}")
    print(f"Virtual path: {change.path.virtual}")

for await (const change of ws.events('/data')) {
  console.log(`Event: ${change.kind}`)
  console.log(`Virtual path: ${change.path.virtual}`)
}

For example, after your application reports an edit to report.csv, the listener prints:

Output

Event: update
Virtual path: /data/report.csv

update means the existing file’s contents or metadata changed. To listen to fewer files, change the path:

Path	Notifications received
`/data/reports`	Changes anywhere inside the reports directory
`/data/*.csv`	Changes to CSV files directly inside `/data`
`["/data/reports", "/data/config.json"]`	Changes under reports or to the config file

Notification types

Each notification includes the virtual path and what happened:

Event	Meaning
`create`	A file or directory was added
`update`	Its contents or metadata changed
`delete`	It was removed
`move`	It was renamed or moved; the notification also includes its previous path
`unknown`	Something changed, but the details are unavailable; check the path again

Connect your VFS

Push: Receive changes from a webhook, stream or external file watcher. See the Disk, S3 and GitHub examples.
Poll: Fetch changes from a service. See the Dropbox, Box and Google Drive examples.

VFS Notifications lists the supported services, Python and TypeScript functions, and how to report a change with ws.notify().

Getting Started

Agents

VFS

Integration

CLIs

Mirage Shell

Agent Profiles

Policy

Runtimes

Configuration

Notifications

Access

Help

How it works

Listen for changes

Notification types

Connect your VFS

​How it works

​Listen for changes

​Notification types

​Connect your VFS

How it works

Listen for changes

Notification types

Connect your VFS