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.

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.