Connect Heeler through an Overlay Network

Heeler joins the network by itself, so the phone needs no Tailscale, ZeroTier, or EasyTier app and no VPN setting. The Mac needs the provider's software, Remote Login (SSH), and herdr. You still log in to the Mac over SSH as usual.

Choose a setup

Prepare the Host below, then follow one provider guide. It sends you to Connect from Heeler when it is time to add the Host.

If you're new to this, start with Tailscale. For a Linux or Windows machine, install the provider's client from its own documentation, then follow the same Heeler steps. Windows also needs the Windows SSH and herdr setup.

These guides all join a network from inside Heeler. If you would rather run a VPN app on the phone and open no port anywhere, Cloudflare Tunnel reaches the Mac with Cloudflare's own client app. It needs a Cloudflare account, and it is not an Overlay Network under Settings.

Heeler setup screenshots

Go to Settings > Overlay Networks > Add Network. Each provider has its own form; EasyTier has two. Tap an image to see it full size.

Tailscale	ZeroTier
Leave Advanced blank and tap Continue to Sign In. Tailscale setup	Enter the network ID and tap Add and Connect. ZeroTier setup

EasyTier Network	EasyTier Config Server
Enter the Mac's network name and secret, and add its peer address. Network setup	Enter the server URL, then assign a network to the Machine ID. Config Server setup

The values shown are examples.

Prepare the Host

Do these steps on the Mac that runs herdr, signed in as the account Heeler will use.

1. Install and start herdr and open the session you want.

2. Turn on System Settings > General > Sharing > Remote Login and allow your account (Apple's guide). Keep the Mac awake.

3. In Terminal, note your username, check herdr, and read the Mac's SSH fingerprint so you can compare it in Heeler later:

   Terminal

   Copy code

   id -un
   herdr --version
   ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

   If Heeler shows a different key type, read that type's .pub file in /etc/ssh/ instead.

4. Pick how Heeler signs in. For Device Key (recommended), go to Heeler > Hosts > Add Host, choose Device Key, tap Copy authorized_keys Line, then cancel the form. Get the line onto the Mac (for example with Universal Clipboard) and run:

   Terminal

   Copy code

   mkdir -p ~/.ssh
   echo 'PASTE_THE_LINE_HERE' >> ~/.ssh/authorized_keys

   For RSA Key, do the same with Copy RSA Public Key. For Password, use your Mac password. A key from pairing also works.

Connect from Heeler

Come here from your provider guide once the Mac and Heeler are on the same network.

1. Open Hosts and tap Add Host. Under Routes, tap Add Route, set Network to your saved network, fill in Address and Port, and tap Save. For Tailscale and EasyTier, you can instead open the network in Settings and tap Add next to the Mac; this pre-fills the route. (Direct means Heeler does not use the overlay network.)
2. Back in Add Host, fill in the remaining fields below and tap Save.
3. Tap Trust only if the fingerprint matches the one from the Mac. If a check fails, fix it and tap Run Checks Again.

To fill in the address on the route page, Tailscale offers Choose from Tailnet… (keep IP Address selected) and EasyTier offers Choose from Network…. For ZeroTier, copy the Mac's IP address from ZeroTier Central.

Verify the connection

Connected here means Heeler has joined the network, not that a Host is using it. Follow the checks below to verify the Host's route. Network names have been anonymized; you only need the network you chose, not all three. Tap the image to enlarge it.

1. The network shows Connected in Settings > Overlay Networks.
2. Open the Host from Hosts and check which route is marked In Use under Routes. Confirm it uses the overlay network you are testing. If another route wins, this connection does not verify the overlay route. See which route is in use.
3. The Host checks pass and the session's Agents or Terminals load.
4. In a New Terminal, pwd prints a folder on the Mac. Use a new terminal for tests, not an Agent's terminal.
5. Turn off Wi-Fi on the phone and repeat over cellular, checking In Use again. Another available route, such as a Jump Host or a different overlay network, can still win.
6. Leave Heeler for more than 20 seconds, then come back. The Host and terminal reconnect; check In Use again to confirm which route reconnected. (Heeler disconnects from the network while you're away; it isn't an always-on VPN.)

Troubleshooting

Last checked on 2026-10-09 on macOS.