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, per-torrent rate limits, sequential-download toggle, and (once the torrent completes) per-torrent seed-limit override. See Sequential download, Per-torrent rate limits, Seed limits.
  • 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. Add or remove trackers from this tab; see Per-torrent trackers.
  • 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 groups panes by category. Visibility varies by build (desktop vs. mosaicd) and account permissions — admin sees all, members see what they’re allowed to manage. Across both builds, the available panes are:

  • General — default save path, watch folder configuration (see Watch folder)
  • Appearance — theme accent color
  • Connection — global down/up cap, alt-speed cap, queue limits (max_active_downloads, max_active_seeds), per-torrent peer cap, listen port, DHT toggle, protocol-encryption toggle, UPnP/NAT-PMP toggle. Listen port / DHT / encryption / UPnP changes take effect on next launch.
  • Seeding — global default ratio and time-min stop conditions (see Seed limits)
  • Web Interface (desktop build only) — remote interface enable, port, bind-all toggle, username, password, API key (with rotate)
  • Users (mosaicd only) — multi-user account management; see Daemon → Users & permissions
  • Updates — auto-update channel + enable toggle
  • Desktop (desktop build only) — tray, close-to-tray, start-minimized, per-event notification toggles
  • Schedule — time-of-day bandwidth rules
  • Blocklist — URL, enable, manual refresh
  • RSS — feeds, per-feed filters, expandable live feed-item browser
  • 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.

Most panes can be pinned to the left-edge icon rail for one-click access. See Sidebar customization.

Where to next