> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Notify agents when files or directories change in the virtual filesystem.

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

1. Your application receives a service notification or checks for changes.
2. It reports each change to Mirage with `ws.notify()`.
3. 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:

```python Python theme={null}
async for change in ws.events("/data"):
    print(f"Event: {change.kind.value}")
    print(f"Virtual path: {change.path.virtual}")
```

```typescript TypeScript theme={null}
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:

```text Output theme={null}
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](/home/notifications/support#push-examples).
* **Poll:** Fetch changes from a service. See the [Dropbox, Box and Google Drive examples](/home/notifications/support#poll-examples).

[VFS Notifications](/home/notifications/support) lists the supported services,
Python and TypeScript functions, and how to report a change with `ws.notify()`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.