Watch Folder

Drop a .torrent file into a directory and Mosaic adds it automatically.

A watch folder is the simplest way to wire Mosaic into other tools that produce .torrent files — RSS-to-torrent bridges, browser extensions that save instead of opening, scripted scrapers, or just a directory on your NAS your other devices can write to.

Mosaic polls the configured directory every 5 seconds; any .torrent file it finds gets added to the engine the same way the + button would, with the global default save path.

Configuration

Settings → General → Watch Folder:

Field Notes
Enabled Master toggle; the watcher only polls when this is on.
Folder path Absolute path to the directory to watch. Browse… opens a native picker (desktop build only).
Delete after add When on, the .torrent file is removed from the folder after a successful add. Off keeps the file in place.

The watcher uses ordinary directory polling (no fsnotify, no inotify dependency) — a 5-second tick fired off os.ReadDir. Restarting the watcher (toggling enabled, changing the path) tears down the previous loop and starts a fresh one; the previous goroutine drains cleanly before the next starts.

What gets added

Every file whose lowercased name ends in .torrent is added with the global default save path. The folder is non-recursive — subdirectories are skipped. Non-torrent files (.txt, partial downloads, hidden files) are ignored.

If a file is malformed or anacrolix refuses to add it, the watcher logs the failure (watch_folder: AddTorrentBytes failed) and moves on; the bad file stays in the folder, and (if delete-after-add is on) is not deleted — only successful adds trigger the delete. Re-fix the file or remove it manually if it’s stuck.

If the same .torrent keeps appearing in the folder, anacrolix’s duplicate-infohash refusal prevents double-adding the same content. But re-add attempts still flow through the watcher every 5 seconds and log AddTorrentBytes failed: ...already exists until the file is removed. Turn delete-after-add on if you want the watcher to clean up after itself.

Caveats

  • Polling, not events. Adding a .torrent to the folder takes up to 5 seconds to be picked up. Don’t expect sub-second pickup.
  • No category or tag routing. Watch-folder additions land in the global default save path with no category and no tags. If you need category-aware routing, use RSS filters instead — they’re per-feed and let you set a category and save path. See RSS.
  • Mosaic must be running. The watcher only ticks while the process is up. Files dropped while Mosaic isn’t running will be picked up on the next start, but only if delete-after-add hasn’t been used to clean them up between runs.
  • Path must exist. If the configured path doesn’t exist or isn’t a directory, the watcher logs a warning and does nothing until you reconfigure with a valid path.
  • Desktop builds only have a native picker. On mosaicd (headless), enter the path manually — there’s no GUI to invoke a file dialog from.

API

GET  /api/settings/watch_folder
PUT  /api/settings/watch_folder        body: { "path": "/some/dir", "delete_after_add": true, "enabled": true }

PickWatchFolder (native directory picker) is still desktop-only since it opens an OS dialog on the user’s machine — that doesn’t have a sensible remote equivalent. The Connection-pane “Browse…” button only appears in the Wails build for that reason; the headless daemon’s web UI expects a manually-typed path.

See also