Setup walkthrough

From a blank machine to a paired iPhone in about ten minutes. No Go toolchain, no Docker — just a pre-built binary, a config wizard, and a quick QR scan. Pick your platform and follow the steps.

Before you start

You'll need:

• A computer that stays on while you listen — Mac, Linux box, Raspberry Pi 4+ (arm64), or Windows 10/11 PC. A modern NAS that runs containers also works (see Docker guide).
• Your music library on a disk that machine can read — a folder of .flac, .dsf, .alac, .m4a, .mp3, and friends. Tags can be missing; the bridge enriches what it can.
• The 1-bit iOS app installed on your iPhone or iPad (iOS 18.6 or newer).
• About 10 minutes the first time. Future updates take seconds.

1. Download for your platform

   Grab the archive matching your OS and CPU from the latest release page. No installer — just unpack.

   macOS

   tar -xzf 1-bit-bridge_*_macos_arm64.tar.gz
   cd 1-bit-bridge_*_macos_arm64

   Apple Silicon → arm64. Intel Mac → amd64. Signed and notarized; Gatekeeper is happy on first run.

   Linux / Raspberry Pi

   tar -xzf 1-bit-bridge_*_linux_arm64.tar.gz
   cd 1-bit-bridge_*_linux_arm64

   Pi 4 / Pi 5 → arm64. x86_64 server → amd64. Static binary — no glibc gymnastics.

   Windows

   Expand-Archive -Path 1-bit-bridge_*_windows_amd64.zip -DestinationPath bridge
   cd bridge

   SmartScreen will warn "unrecognized app" on first run — click More info → Run anyway. Authenticode signing is in progress.

2. Run a preflight check (optional)

   bridge doctor prints a punch list of what's wrong with your environment before you commit to a config. It's safe — it makes no changes.

   ./bridge doctor

   You're aiming for all green. The most common red is port already in use on :7788 or :7789 — close whatever owns those ports, or pick different ones in the next step.

3. Run bridge init

   The init wizard walks you through the minimum you need to start serving music: a library path, a bridge name (shows up on your iPhone), and an HTTPS listen address. Defaults are sane — pressing return is usually fine.

   ./bridge init

   It will ask for:

   • Library path — the top-level folder containing your music. Use an absolute path. Multiple roots can be added later from the admin console.
   • Library name — what your phone shows in the Sources list. "Home library" is fine.
   • Listen address — accept the default :7788 unless that port is taken.
   • Service install — yes, install as a launchd / systemd / Windows Service. The bridge starts on boot and keeps running across logouts.
   If you'd rather not install a service yet, run ./bridge init --no-service --yes and start the bridge manually with ./bridge serve. Quit-on-close, keep-it-simple — recommended for first-time exploration.

4. Open the admin console

   Once bridge init reports success, open http://127.0.0.1:7789/ in any browser on the same machine.

   The admin console is loopback-only — it answers exclusively on 127.0.0.1, never on your LAN or Tailscale IP. There's no login because anyone with a shell on this machine already has access to the data the console manages. From here you can:

   • Library — add or remove root folders, kick off a re-scan, watch progress.
   • Devices — pair iPhones, rotate or revoke tokens, approve pending pair requests.
   • Settings — Tailscale mode, auto-update, quiet hours, backup rotation, optional upscale.
   • Updates — check for new bridge releases, see what's installed, opt in to auto-install.

5. Wait for the first scan

   The bridge starts scanning your library the moment it's pointed at a folder. The Library tab shows live progress: total files found, tagged so far, artwork fetched.

   What "first scan" looks like for typical libraries:

   Approximate first-scan and re-scan durations by library size

   Library size	Approx. first scan	Subsequent re-scans
   2,000 tracks	30 seconds	under 5 seconds
   10,000 tracks	2 minutes	10–20 seconds
   50,000 tracks	5–15 minutes	30–60 seconds

   Times depend on disk speed and how much enrichment (MusicBrainz lookups, artwork downloads) the bridge has to do. The first scan is the slow one because every track gets enriched; later scans only enrich what's new.

   You can pair your iPhone before the scan finishes. The app will stream what's already indexed and pick up the rest as it lands.

6. Pair your iPhone — Method A: tap-to-pair (recommended)

   This is the easiest path on iOS 1.2 and newer. Both devices must be on the same Wi-Fi.

   1. Open the 1-bit app.
   2. Tap + in the Sources list, then Add 1-bit Bridge… → Discover on network.
   3. Your bridge appears in a list — tap it. The app shows a 6-digit verification code.
   4. Switch to the admin console — a yellow Pending pair request banner appears at the top of every page. Click into it.
   5. Confirm the 6-digit code matches what's on your phone, give the device a friendly name (e.g. "My iPhone"), and click Approve.
   6. Your phone's Sources list now shows the bridge as a paired source. Tap into it.

   The verification code prevents an attacker on your network from MITM'ing the pair — only the device that actually holds the matching code is talking to your bridge.

7. Pair your iPhone — Method B: QR / manual entry

   If you'd rather pair from the admin side first (e.g. you're configuring a phone for someone else), use the legacy flow.

   1. In the admin console, open the Devices tab and click Pair new device.
   2. Give it a name and click Generate token. The console shows a QR code encoding a bridge://pair?... URL.
   3. On the iPhone: 1-bit → + → Add 1-bit Bridge… → Scan QR code. Point the camera at the QR.
   4. Or paste the URL, token, and TLS fingerprint manually via Add 1-bit Bridge… → Enter manually.

   Either method ends with the bridge appearing as a paired source in 1-bit. Every subsequent request from the iPhone is bearer-token-authenticated and TLS-fingerprint-pinned.

8. Test playback

   From the iPhone's Sources list, tap into the bridge. Browse to an album. Tap a track. You should hear it within a second or two.

   Check the bottom-of-screen mini-player chip — it should read BIT-EXACT green for FLAC / ALAC / DSF playback. If it shows orange (resampling), iOS hit a sample-rate ceiling on the route — usually means an AirPlay or BT speaker is in the path. Tap the chip for details.

9. Optional: enable remote access via Tailscale

   If you want to listen to your library from outside your home network, the cleanest answer is Tailscale — a free, peer-to-peer VPN. The bridge has built-in support for it.

   Two integration modes are available:

   • tsnet mode (recommended for new installs). The bridge embeds a tailnet node directly in its own process. No system Tailscale install needed; HTTPS certs renew automatically. Authenticate once with ./bridge tsnet auth.
   • cli mode. If you already have Tailscale running on the host (typical desktop setup), this delegates to the system tailscale binary.

   See Features → Tailscale integration for the full rundown — when to choose which mode, the macOS sandboxed-CLI gotcha, and how to verify Magic-DNS works end-to-end.

Alternative: public-internet deployment (v0.1.4)

If you'd rather expose the bridge directly on the public internet — a small VPS for friends and family, a fixed public hostname rather than a tailnet identity, or any setup where Tailscale isn't an option — substitute step 3 above with the public-mode initialiser:

./bridge init --public

Steps 1, 2, 5, 6, 7, and 8 above are unchanged. The public profile differs from the loopback default in three ways:

• Admin console password. The init wizard generates a 16-character random password and prints it once. Copy it somewhere safe; rotate later with ./bridge admin reset-password.
• Let's Encrypt cert. If you set autocert.enabled: true with a public domain pointed at the host, the bridge fetches a real TLS cert automatically. No reverse proxy needed.
• Reachable admin console + TLS-port shift. The admin listener binds a routable interface (not 127.0.0.1) so you can manage the bridge from another machine, and the iOS-facing TLS listener defaults to :443 instead of the loopback default :7788 — Let's Encrypt's TLS-ALPN-01 challenge only validates on TCP/443.

Lock down what you expose: open only the bridge's TLS port (:443 with this profile, unless you overrode it with --listen-address) and, if you need remote admin, the admin port (default :7789) — keep the admin port firewalled to the operator's IP via your VPS firewall / ufw / cloud security group.

Something not working?

Check the troubleshooting page for common symptoms — bridge not appearing in Discover, "Server unreachable" errors, slow scans, certificate-rotation flow. If your problem isn't listed, open an issue on GitHub.

Next steps

Once you have playback working:

• Browse the full feature set — admin-approval pairing, upscale variants, the folder-first Library Inspector, Tailscale modes, auto-updates, backups.
• Read the wire protocol if you want to write your own client.
• Read the privacy policy — what's stored, what's sent out, what's deliberately not logged.