Pairing & Remote

This page explains how connection, pairing, and remote access fit together in the current product (0.3.0+).

The Basic Model

Music Hub works best when you think about it this way:

the desktop app is the hub
the phone app is the paired client
pairing creates a private relationship between that phone and that hub

First Pairing

The safest default is still:

open the hub locally, either in the desktop app or Docker web UI
arm pairing if needed
scan the current QR code from the mobile app
complete the first connection on the same Wi-Fi

During an active pairing window, the desktop can expose:

a QR code (includes hub identity for Personal Private network)
a share link (HTTPS, for WhatsApp and chat)
an app deep link (musichub://connect?...) used after the share page opens the app
a countdown/expiry time
a relaunch action for a fresh pairing window

Update desktop and mobile together before relying on remote listening.

Share link (chat)

musichub:// links are poor for messaging apps (often not clickable). While pairing is armed, desktop Copy / Share uses an HTTPS URL on the product landing, not on your hub’s public remote hostname:

https://tape-music-hub.gordo.design/mobile-pair?server=https%3A%2F%2Fyour-hub.example&name=...&pair=...

Flow:

Recipient opens the link in the phone browser (landing).
They tap Open in Music Hub → musichub://connect?... with the same parameters as the QR.
The hub still validates the pairing code on POST /api/auth/pair.

The hub’s public remote URL (when configured) remains the API endpoint (server in the query). The landing only mediates deep linking; it does not grant access by itself.

Desktop env override if your landing host differs: MUSIC_HUB_PAIRING_LANDING_ORIGIN (origin only, no path).

Connection Priority

The phone keeps one hub identity and moves between routes as needed.

Current priority:

local Wi‑Fi / LAN
Personal Private network (Iroh)
public remote route (Cloudflare / public link), when configured

Pair once on Wi‑Fi. Later, away from home, the phone can use Personal Private network without Tailscale.

Remote Access Options

Local Wi‑Fi

fastest path
best default for first pairing
no internet dependency if both devices are on the same network

Personal Private network

always on in Settings → Remote (0.3.0+)
built into the hub (Iroh); no Tailscale app, no inbound port-forward
treated as remote for licensing
pairing QR embeds hub identity so reconnect works after the first pair
on Docker, needs UDP 42424 published and MUSIC_HUB_ADVERTISED_LOCAL_IP set — see Docker Setup

Public remote route

optional Cloudflare / public link from the desktop hub
useful for first-time pairing off Wi‑Fi when you share a public URL + pairing code
still not anonymous private library access; the phone must complete pairing/auth

Note: Tailscale is no longer a Music Hub Settings path. If you previously depended on Tailscale alone, update to 0.3.0 and re-pair the phone.

Keep the Desktop Hub Available

The desktop app is the hub: remote routes and phone playback work only while it is running.

In Settings → General, you can enable Keep Music Hub running in the tray when the window closes. Closing the window then hides it while the local server and remote routes keep running. Use Quit in the tray menu or Cmd/Ctrl+Q to stop the hub completely.
In Settings → Remote, Keep this hub active is on by default and prevents the Music Hub process from being suspended. If you turn it off, the desktop header shows a warning that opens that setting again.
This does not override a closed laptop lid, logout, low-battery shutdown, or your operating system's power policy. Keep the computer connected to power when you need dependable long remote sessions.

Public Scope vs Private Mobile Access

One of the most important product rules:

Shared pages only limits the public web/share surface
it does not remove private access from a phone that is already paired

So if your phone was already paired correctly, it should still be able to browse and play through the private mobile API even when the public share scope is narrow.

Public hub root vs share links

If someone opens the hub’s public base URL (for example your stable Cloudflare hostname) without a /share/... path, what they get depends on Public web access / publicRemoteScope on the desktop:

Shared pages only (standalone_only): the hub returns a small HTML splash page (not the full web app). It explains that visitors need an explicit share link to hear anything, and points people who want to host their own library to tape-music-hub.gordo.design (opens in a new tab) for downloads and setup.
/share/playlist|album|artist|track/... URLs still load the interactive standalone player for that shared item. That surface is separate from “browsing the whole hub in a browser.”

The hub pill on standalone share pages opens an overlay that reuses the same messaging and primary CTA as that splash (Get Music Hub → the marketing/docs site).

Licensing and Remote

Current product rule:

LAN / Wi-Fi remains available without remote entitlement
remote playback requires a valid desktop license

If remote is blocked by license:

the phone should still work on Wi‑Fi
the app should tell you remote needs a valid desktop license
it should not look like a random generic network failure

Common Failure Modes

`pairing_not_armed`

The desktop has a route, but pairing is not currently armed.

What to do:

open the desktop app locally
arm pairing again
refresh the QR and rescan it

Old QR or stale route

If the phone is using an old QR or stale public route:

rescan the latest desktop QR
confirm the hub still exposes the expected routes
update desktop and mobile if one side is below 0.3.0

Remote works, but browse/search/playback fail

That usually means:

auth is stale, or
remote is present but the mobile private-access path is not healthy

Start by reconnecting from the latest QR and checking the desktop remote state.

Features FAQ