Remote Watcher

The pellicle-watcher is a lightweight service that runs on your NAS and works alongside Pellicle to manage your photo library over the network. It provides three core capabilities: real-time file monitoring, HTTPS file transport, and local thumbnail caching.

How It Works

The watcher monitors your photo directories using the Linux kernel's inotify subsystem. When files are created, modified, renamed, or deleted, the watcher sends notifications to Pellicle over a persistent WebSocket connection. Pellicle receives these events and updates its index immediately, so new photos appear in your library without waiting for a periodic rescan.

All communication between Pellicle and the watcher is encrypted with TLS. On first start, the watcher generates a self-signed ECDSA certificate. Pellicle uses Trust On First Use (TOFU) to verify the watcher's identity — the first time it connects, it accepts the certificate and saves its SHA-256 fingerprint. All subsequent connections must present the same certificate.

Features

Real-Time File Monitoring

The watcher uses inotify to detect changes across all configured watch roots. Events are debounced (coalesced over a 500ms window) to avoid flooding Pellicle with rapid successive changes, such as when copying a batch of photos. Hidden files, Synology system directories (@eaDir), and recycle bin paths are automatically filtered out.

When Pellicle first connects (or reconnects after a network interruption), it can request a sync snapshot — a complete listing of all files with their modification times and sizes. Pellicle compares this against its index to detect any changes that occurred while disconnected.

HTTPS File Transport

The watcher provides an HTTPS API that Pellicle uses to read files directly from the NAS without requiring an SMB mount. This includes:

• Thumbnail generation — the watcher serves file data so Pellicle can generate thumbnails locally on your Mac's SSD for fast browsing
• Full-resolution viewing — when you open a photo in detail view, Pellicle downloads the full file via HTTPS
• Metadata extraction — EXIF, IPTC, and other metadata is read via the watcher's file API
• Sidecar management — XMP and DOP sidecar files are read and written through the watcher

The HTTPS transport eliminates the need for SMB volume mounts entirely. Folders configured with the watcher transport mode in Pellicle's settings use the watcher for all file access.

I/O Concurrency Control

The watcher limits concurrent file operations to prevent overwhelming the NAS disk. By default, it allows up to 8 concurrent reads and 4 concurrent writes. Operations beyond these limits are queued and processed in order. These limits can be tuned in the configuration file.

Automatic Discovery

When mDNS is enabled, the watcher advertises itself as a _pellicle._tcp service on the local network. Pellicle discovers it automatically in the Remote Watchers settings — no need to enter IP addresses manually.

Admin Panel

An optional web-based admin panel provides a dashboard showing connection status, uptime, and TLS certificate details. It also lets you manage watch roots, toggle mDNS, and regenerate the authentication token. See Configuration for details.

Deployment

The watcher runs as a Docker container or as a native Synology package:

• Synology NAS Setup — native package (recommended) or Docker
• QNAP NAS Setup — using Container Station
• SSH / Command Line Setup — for Unraid, generic Linux, or any system with SSH access

Connecting Pellicle

1. Open Pellicle > Settings (or press ⌘,).
2. Go to the Remote Watchers tab.
3. If mDNS discovery is working, your watcher should appear automatically. Click it to add it.
4. Otherwise, click Add Watcher and enter the URL (e.g. wss://192.168.1.100:7849) and the token.
5. Assign the watcher to an indexed folder by selecting the folder in the sidebar, then choosing the watcher and the matching watch root in the folder settings.
6. To use HTTPS file transport instead of SMB, set the folder's transport mode to Watcher in the folder settings.

Once connected, the folder icon in the sidebar indicates the connection state. A green icon means the connection is active.

Troubleshooting

Watcher not discovered automatically

• Ensure mdns.enabled is true in config.yml.
• Verify network_mode: host is set in docker-compose.yml. Without it, mDNS packets can't reach the local network.
• Some NAS models restrict mDNS from containers. Try adding the watcher manually using its IP address instead.

Connection fails or keeps reconnecting

• Check that the token in Pellicle matches the one in config.yml exactly.
• Ensure port 7849 (or your chosen port) is not blocked by a firewall.
• Check the watcher logs: docker compose logs pellicle-watcher.

Certificate fingerprint mismatch

If the watcher's certificate changes (e.g. the TLS volume was deleted, or the container was recreated without a persistent volume), Pellicle will reject the connection because the fingerprint no longer matches. To fix this:

1. In Settings > Remote Watchers, remove the affected watcher.
2. Re-add it. Pellicle will trust the new certificate on first connection.

Increasing inotify watches

For very large photo libraries, you may need to increase the inotify watch limit. If your NAS supports container sysctls, add this to docker-compose.yml:

    sysctls:
      - fs.inotify.max_user_watches=524288

Otherwise, set it on the host system:

echo 524288 | sudo tee /proc/sys/fs/inotify/max_user_watches