Installation

Mosaic ships pre-built binaries for macOS (universal), Linux (amd64), and Windows (amd64) on every release. Grab the appropriate asset from GitHub Releases and unpack — there’s no installer step beyond that.

Release assets

Every release publishes a fixed set of versioned assets. Replace vX.Y.Z with the version tag you want; for the very latest, the releases page is the canonical entry point.

There is no Linux tarball and no Windows zip variant. The macOS .dmg is for fresh installs only — the auto-updater consumes a separate .tar.gz asset (see Auto-Update).

macOS

The macOS .dmg is signed when the build secrets (APPLE_DEVELOPER_ID and friends) are configured in CI; releases built without those secrets are unsigned and will require the usual right-click → Open dance on first launch.

Open the .dmg and drag mosaic.app into /Applications.

# Or from the command line — replace vX.Y.Z with the actual version tag.
curl -LO "https://github.com/exec/mosaic/releases/download/vX.Y.Z/Mosaic-vX.Y.Z-darwin-universal.dmg"
hdiutil attach "Mosaic-vX.Y.Z-darwin-universal.dmg"
cp -R "/Volumes/Mosaic/mosaic.app" /Applications/
hdiutil detach "/Volumes/Mosaic"
open /Applications/mosaic.app

The .torrent and magnet: registrations come from the bundle’s Info.plist — CFBundleDocumentTypes for .torrent files and CFBundleURLTypes for the magnet: URL scheme. At runtime, Wails’s AppDelegate routes incoming opens to Mac.OnFileOpen (the receiver, not the registrar), so double-clicking a .torrent or clicking a magnet: link in your browser opens (or focuses) Mosaic.

Linux

Three flavors are built per release: a .deb, an .rpm, and an AppImage. There is no portable tarball.

Debian / Ubuntu via apt

For Debian 12+ and Ubuntu 22.04+, the recommended install is via the repo.x86-64.com apt repository — apt update keeps both the GUI (mosaic) and the headless daemon (mosaicd) on the latest published version automatically.

# 1. Add the signing key
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://repo.x86-64.com/exec.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/exec.gpg

# 2. Add the repository
echo "deb [signed-by=/etc/apt/keyrings/exec.gpg] https://repo.x86-64.com/ stable main" \
    | sudo tee /etc/apt/sources.list.d/exec.list

# 3. Install
sudo apt update
sudo apt install mosaic       # GUI desktop client
# OR
sudo apt install mosaicd      # headless daemon (see Daemon docs)

The repo is signed with key 318B7812 99D5 C05B 2A0C 8F0F 88C3 F86B E415 C388 (exec apt repository <repo@x86-64.com>). You can verify the fingerprint after import with gpg --show-keys /etc/apt/keyrings/exec.gpg.

The GUI package depends on libwebkit2gtk-4.1-0 + libgtk-3-0. Older systems without -4.1 (Ubuntu 20.04 and prior) should use the AppImage which bundles its own webkit.

Tray icon on Gnome

Vanilla Gnome (the default on Debian and Fedora) deliberately ignores the StatusNotifierItem protocol that powers our tray icon. The package recommends gnome-shell-extension-appindicator, which apt’s desktop default (--install-recommends) pulls in automatically — but you still need to enable it once via the Extensions app (or gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com) and either log out + back in or restart the shell.

Without the extension, Mosaic detects this at startup and disables close-to-tray for the session, so the X button quits cleanly instead of stranding the window in a tray that doesn’t exist. KDE Plasma, XFCE, MATE, Cinnamon, and Budgie all show the tray icon natively with no extra setup.

One-shot .deb / .rpm download

If you don’t want to add the repository, the per-release .deb and .rpm are still on GitHub Releases:

# Debian / Ubuntu — replace vX.Y.Z with the actual version tag.
curl -LO "https://github.com/exec/mosaic/releases/download/vX.Y.Z/Mosaic-vX.Y.Z-linux-amd64.deb"
sudo dpkg -i "Mosaic-vX.Y.Z-linux-amd64.deb"
mosaic

# Fedora / RHEL
curl -LO "https://github.com/exec/mosaic/releases/download/vX.Y.Z/Mosaic-vX.Y.Z-linux-amd64.rpm"
sudo rpm -i "Mosaic-vX.Y.Z-linux-amd64.rpm"
mosaic

# AppImage — single-file portable
curl -LO "https://github.com/exec/mosaic/releases/download/vX.Y.Z/Mosaic-vX.Y.Z-linux-amd64.AppImage"
chmod +x "Mosaic-vX.Y.Z-linux-amd64.AppImage"
./Mosaic-vX.Y.Z-linux-amd64.AppImage

The .deb and .rpm packages register the desktop entry and MIME associations automatically. The AppImage is single-file portable — you can wire its .desktop integration manually if you want associations.

Windows

Two flavors are built per release: a Windows installer (.exe) and a portable single-file .exe. There is no .zip.

# PowerShell — installer (replace vX.Y.Z with the actual version tag)
Invoke-WebRequest "https://github.com/exec/mosaic/releases/download/vX.Y.Z/Mosaic-vX.Y.Z-windows-amd64-installer.exe" -OutFile "Mosaic-Setup.exe"
.\Mosaic-Setup.exe

# PowerShell — portable
Invoke-WebRequest "https://github.com/exec/mosaic/releases/download/vX.Y.Z/Mosaic-vX.Y.Z-windows-amd64-portable.exe" -OutFile "Mosaic.exe"
.\Mosaic.exe

Windows builds self-heal file associations on startup — even if a previous install left stale per-user HKCU\Software\Classes\MosaicTorrent keys, the running binary rewrites them on first launch (so a fresh install on top of an old one always wins).

The Windows shell also forwards a .torrent path to an already-running Mosaic instance before the second instance binds to its port — so double-clicking files always lands on the existing window rather than firing up a duplicate.

Configuration storage

Mosaic stores its database, certificates, and settings under OS-conventional paths via adrg/xdg. On macOS the config / data / state directories collapse to a single bundle directory; on Linux they diverge per the XDG Base Directory spec.

The DataDir contains:

• mosaic.db — SQLite database (torrent records, categories, tags, settings, schedule rules, RSS feeds + filters)
• engine/ — anacrolix piece state and metainfo cache
• web-tls/cert.pem and web-tls/key.pem — self-signed ECDSA P-256 cert generated on first run only when the remote interface is enabled with bind_all = true. Loopback-only mode does not generate or use a cert.

Resetting Mosaic is as simple as deleting the relevant directories. Torrent files on disk are untouched.

First-run defaults

• Default save path: OS download folder (~/Downloads on Unix, %USERPROFILE%\Downloads on Windows)
• Listen port: anacrolix picks a free port; reconfigurable in Settings → Connection
• DHT: on
• Encryption: on (preferred; falls back to plaintext if peer rejects)
• Auto-update: on, stable channel
• Remote interface: off (loopback-only when first enabled)

Verifying release integrity

Each release publishes a SHA256SUMS manifest alongside the binaries:

curl -LO "https://github.com/exec/mosaic/releases/download/vX.Y.Z/SHA256SUMS"
shasum -a 256 -c SHA256SUMS --ignore-missing

The auto-updater pulls and verifies this manifest before swapping the running binary; the same manifest is what you should check against if you’re installing manually.