Guide

Setting up the launchpad

For playing your library away from home. Not needed on your own Wi-Fi.

minstrel-launchpad is a small program that runs at home, next to your media server. Away from home, the Minstrel app connects to it, and it passes the app's requests to your media servers and nothing else. Only devices you paired get in; each has its own key, and you can remove any of them.

It connects to the app in one of two ways:

Direct: the app connects straight to your home through one port on your router. Needs a fixed way to find your home on the internet: a static IP or a dynamic DNS name.
Headscale: coming soon. For homes that can't open a port (see below).

1. Choose where it runs

Anything that stays on and sits on the same network as your media server: the NAS itself, a router, a Raspberry Pi, a home server or an always-on computer. It needs very little: one small program, about 15 MB of memory.

It must be able to see the media server's network directly. In Docker, use host networking; in a NAS jail or VM, give it its own address on the home network (bridged, not NAT).

Give the machine a fixed address on your home network (a DHCP reservation on the router, or a static address outside the DHCP range): your router's port forwarding points at it.

2. Install

Ready-made downloads come with the first release. Until then, install it one of these ways:

Docker (most NAS boxes)

docker build -t minstrel-launchpad https://github.com/imush/minstrel-launchpad.git
docker run -d --name launchpad --network host --restart unless-stopped \
  -v launchpad:/data minstrel-launchpad
docker logs launchpad          # shows the console's setup link

Host networking is required, so it can discover your media servers.

Linux (Raspberry Pi, home server)

With Go installed:

GOBIN=/tmp go install github.com/imush/minstrel-launchpad@latest
sudo install -m 755 /tmp/minstrel-launchpad /usr/local/bin/
sudo curl -o /etc/systemd/system/minstrel-launchpad.service \
  https://raw.githubusercontent.com/imush/minstrel-launchpad/main/contrib/linux/minstrel-launchpad.service
sudo systemctl enable --now minstrel-launchpad
journalctl -u minstrel-launchpad    # shows the console's setup link

To build for another machine (a Pi, a NAS), set GOOS and GOARCH, for example GOOS=linux GOARCH=arm64, and copy the program over.

FreeBSD, TrueNAS CORE jail, OPNsense, pfSense

On TrueNAS CORE, create a jail with VNET on, a fixed IPv4 address on your home network (bridged, as with your other jails), and auto-start. Build the program for FreeBSD on any computer with Go:

git clone https://github.com/imush/minstrel-launchpad && cd minstrel-launchpad
GOOS=freebsd GOARCH=amd64 CGO_ENABLED=0 go build -o minstrel-launchpad .

Copy minstrel-launchpad to /usr/local/bin/ and contrib/freebsd/launchpad to /usr/local/etc/rc.d/ in the jail, then inside it:

chmod 755 /usr/local/bin/minstrel-launchpad /usr/local/etc/rc.d/launchpad
pw useradd launchpad -d /nonexistent -s /usr/sbin/nologin
sysrc launchpad_enable=YES
service launchpad start
cat /var/log/launchpad.log          # shows the console's setup link

macOS or Windows

Fine on a computer that already runs your media server and stays on. Build it with Go as above and run minstrel-launchpad serve, at login or as a service.

3. Open the console

The launchpad's web console is at http://its address:7444, reachable from your home network only.

Open the setup link from its log (it's valid for an hour; restarting the launchpad prints a new one).
Choose a console password. It protects the console only, so guests on your Wi-Fi can't pair themselves; the app never asks for it.
Give the home a Name, the way the app should show it, such as “Lake house”.
Check Media servers: yours should be listed. If one is missing, add its description URL by hand.

4. Direct mode: reach home from outside

The app needs an address on the internet that always leads to your home. That's one of:

A static IP from your internet provider. Use it as is.
A dynamic DNS name, if your IP changes from time to time (most home connections). A dynamic DNS service gives you a name like myhome.example.net and keeps it pointed at your current IP. Many routers update it themselves (pfSense and OPNsense: Services → Dynamic DNS; most consumer routers have a DDNS page); otherwise run a client such as ddclient at home. Providers include your own domain's DNS host, DuckDNS, No-IP, Dynu and others.

Then forward a port on your router: TCP, from an outside port of your choice to the launchpad's address, port 7443.

443 is the best outside port if it's free: hotel, office and some mobile networks block everything else.
Never forward 7444, the console. It refuses outside visitors anyway.
On pfSense or OPNsense: Firewall → NAT → Port Forward → Add; interface WAN, protocol TCP, destination WAN address and your outside port, redirect target the launchpad's address and port 7443; keep “add associated filter rule”.

Finally, tell the launchpad: on the console under Outside access → Direct, enter the static IP or dynamic DNS name with the outside port, for example myhome.example.net:443, and save. Paired phones learn it the next time they connect at home; new invitations include it.

Check it

With Wi-Fi off on your phone, open https://myhome.example.net:443/ in its browser. A certificate warning followed by “404 page not found” means it works: that's the launchpad, which shows nothing to strangers. (Testing from inside your home may fail even when all is well: many routers don't loop back to their own public address.)

When direct mode can't work

Carrier-grade NAT. If the address your router shows as its WAN IP is different from the one sites like “what is my IP” report, or starts with 100.64 to 100.127, your provider shares one public address among many homes, and no port can be opened. Ask the provider for a public IP, or wait for Headscale mode.
Two routers. If your router sits behind your provider's router, forward the port on both, or put the provider's box in bridge mode.

5. Pair your devices

On the console, under Pair a device, enter who it's for and choose how long the invitation is valid:

10 minutes: a QR code to scan right away. In the app, tap Add home (the house with a +) and scan it.
1 day or 7 days: a pairing file to send by email or chat. On the phone, open it in Minstrel with Add home → Open pairing file.

Each invitation works once. The console lists Paired devices with when each last connected and from where; Revoke removes one. In the app, the home appears under Homes; ⋮ → Rename names it just on that phone.

Headscale mode Coming soon

For homes behind carrier-grade NAT, or anyone who'd rather not open a port. The launchpad and your phones join a private network run by Headscale, a self-hosted, open-source coordination server compatible with Tailscale clients. Your home then needs no open port and no public address; the connection is end-to-end encrypted, and a relay is used only when a direct path can't be found. You'll be able to run your own Headscale server, or use one someone you trust runs. Watch the repository for it.

How it's kept safe

The app trusts only your launchpad's own key, pinned at pairing, so no one in between can pose as it.
Each device has its own token, revocable on the console. Requests without one get nothing but “404”, and repeated failures are blocked.
It relays only to the media servers it found or you listed, never as an open proxy.
The console answers the home network only, and is password-protected.
Back up its data directory: it holds the key. Lose it and every device must pair again.

Troubleshooting

“Can't reach home” in the app: the Homes list shows each address tried and what happened. “No answer” on the outside address usually means the port forward or dynamic DNS isn't right; check with the browser test above.
No media servers on the console: the launchpad isn't on the same network segment as the server, or multicast is blocked. In Docker use --network host; in a jail or VM use bridged networking. Or add the server's description URL by hand.
Forgot the console password: run minstrel-launchpad console on the launchpad for a new setup link (add -data with its data directory if you set one, such as -data /var/db/launchpad in a FreeBSD jail, as the user it runs as).

More detail, all options and the API are in the README. Questions: GitHub issues.