Optional Mac companion
Set up Skerry Relay
Skerry Relay connects the iPhone or iPad app to the Herdr session on your Mac. It powers the agent status board and can send content-free attention notifications while Skerry is in the background.
Relay does not carry terminal traffic. Skerry still uses SSH or mosh for the terminal; Herdr owns agent status. You can use Skerry without Relay for ordinary SSH and tmux work.
Before you start
- A Mac running Herdr, with its local socket available at
~/.config/herdr/herdr.sock. - A Skerry Relay source checkout supplied with your beta invitation, Xcode 26 or a Swift 5.9+ toolchain, and a Tailscale tailnet shared by the Mac and phone.
- Permission to install a per-user LaunchAgent on that Mac. Keep the Mac awake and connected for background status and notifications.
The source checkout is distributed to invited testers; the beta application does not grant source access automatically.
Install the daemon on the Mac
- In the Skerry Relay checkout, run
swift testand confirm the package passes. - Create
~/.config/skerry-relay/tls/, change into that directory, and runtailscale cert <node>.<tailnet>.ts.netfor this Mac's Tailscale name. Keep the generated private key on the Mac. - Back in the checkout, run
Scripts/install-daemon.sh --tls-name <node>.<tailnet>.ts.net. The script buildsskerry-relaydand loads its LaunchAgent. - Check that
~/Library/LaunchAgents/com.johnferguson.skerry-relay.daemon.plistpoints to the built binary. The daemon log is/tmp/skerry-relay-daemon.log; redact it before sharing.
Renew the Tailscale certificate and rerun the installer when the certificate expires or after upgrading the daemon. The default listener port is 7788. Do not expose that port to the public internet.
Connect Skerry
- Connect the phone and Mac to the same tailnet.
- In Skerry, edit the Herdr host and enter
wss://<node>.<tailnet>.ts.net:7788in the Skerry Relay field. - Save the host, connect, and open Skerry Relay from the host list to check the status board.
Leave the Relay field blank if you only want SSH-based multiplexer control. If the board does not connect, check that Herdr, the LaunchAgent, Tailscale, and the certificate are running on the Mac before changing the phone's host settings.
Background notifications
Push delivery is an optional, separately configured beta feature. It requires an Apple APNs provider key and a matching sandbox or production configuration; the tester should obtain the setup instructions from the beta team. A connected status board does not prove that locked-phone notifications work. Do not send an APNs key, certificate private key, token archive, or daemon log through the beta application form.