apt install mosaic (GUI) or apt install mosaicd (headless) — see apt repository setup.mosaicd ships a headless Linux daemon for servers and NAS. Issues and patches welcome at exec/mosaic.
Anacrolix Engine
Battle-tested Go BitTorrent engine: DHT, PEX, LSD, uTP, magnet metadata fetch, encrypted peer connections, IP blocklists, and per-torrent piece priorities. Mosaic adds queue, scheduling, and persistence on top.
Native Desktop Shell
Wails wraps a single SolidJS+Tailwind frontend in a native window per platform. System tray, OS notifications, .torrent & magnet file associations, single-instance launch with arg forwarding, dock-click reactivation on macOS.
Headless Daemon
Same engine, no GUI. mosaicd is a long-running service that exposes Mosaic exclusively through its HTTPS+WebSocket interface and the embedded SPA — qBittorrent-nox–style, server-friendly, systemd-managed. Distributed via the x86-64.com apt repository so a Debian or Ubuntu host installs and updates it like any other system package.
Remote Web Interface
Optional HTTPS server bound to loopback or LAN. The browser loads the same SPA bundle and talks REST + WebSocket back. Auth: Argon2id password sessions or rotatable bearer API key. SameSite=Strict cookies, Origin-pinned WebSocket.
Categories & Tags
Categories are a 1:N grouping with an optional default save path. Tags are M:N labels. Both are first-class in the UI and the API; setting a torrent's category at add-time picks up the category's save path.
RSS with Regex Filters
Subscribe to feeds at a configurable poll interval. Per-feed regex filters auto-add matching items, optionally routing them to a category or save path. ETag-aware fetches; SSRF-guarded URL validation.
Bandwidth Scheduling
Time-of-day rules (day-of-week mask + start/end minute) override the global limits — or flip the alt-speed toggle. Useful for nightly seeding bursts, weekday throttles, or capping during work hours.
Seed Limits
Auto-pause completed torrents at a ratio or seed-time target. Global defaults plus per-torrent overrides — set a 2.0 default and override individual rarities to seed forever, or vice versa.
Sequential Download
Per-torrent toggle that biases piece priorities toward earliest-first, so media files can be previewed before the whole download arrives. Persists across restarts.
Per-Torrent Rate Caps
Cap a single torrent's download or upload speed independent of the global limit. Implemented as a duty-cycle goroutine since anacrolix has no native per-torrent limiter.
Watch Folder
Drop a .torrent file into a configured directory and Mosaic adds it automatically every 5 seconds. Optional delete-after-add to keep the folder tidy.
Per-Torrent Trackers
Add or remove tracker URLs on a running torrent from the inspector's Trackers tab. User-added trackers persist; removed metainfo trackers stay removed across restarts.
IP Blocklist
Fetches a remote P2P-format blocklist (e.g. emule.nl-style ranges), verifies the URL against an SSRF allow-list, parses up to 50 MB, and applies the ranges to the engine's peer filter. Manual refresh, on/off toggle.
Auto-Update
GitHub Releases as the source of truth. SHA-256 manifest verified before binary swap. Stable / beta channels. Cross-platform: per-asset filename matcher pinned and tested against tarball + DMG inner-name conventions.
Hardened by Audit
v0.1.22 closed eight audit items: Argon2id password storage, rate-limited login, single-flight session store, Origin/Referer CSRF guard, WebSocket Origin pin, SameSite=Strict cookies, SSRF-validated outbound fetches, and a session cap.
Documentation
Getting Started
- Installation — Per-platform install, first-run, default save path
- Getting Started — Adding torrents, queue + categories tour, settings overview
- Architecture — Process layout, package boundaries, persistence model
Features
- Categories & Tags — Grouping, save-path inheritance, tagging
- RSS Feeds — Feeds, filters, regex matching, auto-add (magnet + .torrent), live feed browser
- Watch Folder — Drop-folder auto-add
- Scheduling — Time-of-day bandwidth rules, alt speed
- Seed Limits — Ratio + time stop conditions, global defaults and per-torrent overrides
- Sequential Download — Per-torrent earliest-first piece priorities
- Per-Torrent Rate Limits — Cap single-torrent up/down speed
- Per-Torrent Trackers — Inspector-tab add/remove of tracker URLs
- IP Blocklist — Format, fetch model, refresh
- Sidebar Customization — Pin, unpin, reorder the left icon rail
- Desktop Integration — Tray, notifications, file associations, single-instance, magnet handler
Web Interface & API
- Web Interface Setup — Enabling, binding, password, API key
- API Overview — Base URL, auth model, error shape, transport
- Authentication — Login flow, session cookies, bearer keys, CSRF
- REST Endpoints — Every route, request/response schema, errors
- WebSocket — Upgrade, frame types, payload schemas
- Worked Examples — curl + Python + JavaScript end-to-end flows
Operations
- Security — Auth model, CSRF, hardened items, recommendations for non-LAN exposure
- Auto-Update — Channel, manifest verification, per-platform asset mapping, history