Getting Started

A short tour of the Mosaic UI — adding torrents, the queue, categories, and where the settings live.

This page assumes Mosaic is installed and running. If not, see Installation.

Adding a torrent

There are three ways to add a torrent. All of them end up calling the same engine paths under the hood.

  1. Drag-and-drop: drop a .torrent file or a magnet: URL onto the main window.
  2. Open With: double-click a .torrent from your file manager (associations are registered on install or first launch). On macOS, opens are routed through Wails’s Mac.OnFileOpen / OnUrlOpen (registration is in the bundle’s Info.plist); on Windows the binary forwards the path to an already-running instance before the second instance can bind.
  3. The “+” button in the toolbar opens an Add dialog with explicit save-path, category, and tag pickers.

The Add dialog will pre-fill the save path with the active category’s default_save_path if a category is selected, otherwise the global default.

The torrent list

The main view is a table of every torrent the engine knows about. Default sort is newest-first by add time. Each row shows progress, name, size, rates, peers/seeds, ETA, and the assigned category + tag chips.

Right-click a row (or use the toolbar buttons with one or more rows selected) for:

  • Pause / Resume / Force start
  • Recheck (re-verifies pieces against the on-disk files)
  • Set queue position / Move to top / Move to bottom
  • Set category / Add tags
  • Open save folder
  • Remove (with optional “delete files” toggle)

The inspector

Selecting a torrent opens the inspector pane. Tabs:

  • Overview — totals, ratio, magnet, save path, added/completed timestamps
  • Files — per-file progress with per-file priority (skip / normal / high / max)
  • Peers — IP, client, flags, country, per-peer rates
  • Trackers — URL, status, last/next announce, peers/seeds reported
  • Speed — recent download/upload rate sparkline

The inspector is driven by the inspector:tick WebSocket frame (or the equivalent Wails event in the desktop shell). Setting the focus is a single API call (POST /api/inspector/focus with id + the list of visible tabs) so the backend can scope the per-tick payload to what the UI actually needs.

Queue

The queue caps how many torrents can actively download or seed concurrently. Torrents over the limit show as “queued” in the row. The order is set by queue_position (drag-and-drop in the UI; POST /api/torrents/queue_position over the API).

force_start on a torrent bypasses the queue entirely — useful for “I want this one to seed regardless of my limits” cases.

Queue limits live under Settings → Connection (in the Queue subsection of the Connection pane):

  • max_active_downloads — concurrent active downloads
  • max_active_seeds — concurrent active seeds

Settings

The settings sidebar has eleven panes:

  • General — default save path, language, theme
  • Connection — global down/up cap, alt-speed cap, queue limits (max_active_downloads, max_active_seeds), per-torrent peer cap, listen port, DHT toggle, encryption toggle. Listen port / DHT / encryption changes take effect on next launch.
  • Web Interface — remote interface enable, port, bind-all toggle, username, password, API key (with rotate)
  • Updates — auto-update channel + enable toggle
  • Desktop — tray, close-to-tray, start-minimized, per-event notification toggles
  • Schedule — time-of-day bandwidth rules
  • Blocklist — URL, enable, manual refresh
  • RSS — feeds and per-feed filters
  • Categories — manage categories (name, color, default save path)
  • Tags — manage tags (name, color)
  • About — version info, links

Settings panes vary in persistence model: some auto-save on toggle (e.g. the Desktop integration toggles), others use explicit Save / Discard buttons (e.g. the Web Interface pane). Refer to each pane’s UI — the convention is that a pane with a visible Save button does not persist until you click Save.

Where to next