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

The source checkout is distributed to invited testers; the beta application does not grant source access automatically.

Install the daemon on the Mac

  1. In the Skerry Relay checkout, run swift test and confirm the package passes.
  2. Create ~/.config/skerry-relay/tls/, change into that directory, and run tailscale cert <node>.<tailnet>.ts.net for this Mac's Tailscale name. Keep the generated private key on the Mac.
  3. Back in the checkout, run Scripts/install-daemon.sh --tls-name <node>.<tailnet>.ts.net. The script builds skerry-relayd and loads its LaunchAgent.
  4. Check that ~/Library/LaunchAgents/com.johnferguson.skerry-relay.daemon.plist points 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

  1. Connect the phone and Mac to the same tailnet.
  2. In Skerry, edit the Herdr host and enter wss://<node>.<tailnet>.ts.net:7788 in the Skerry Relay field.
  3. 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.

Apply for beta access Get setup help