Pair a Host by scanning a code

Show a Pairing Code on the machine that runs herdr and scan it in Heeler. The Host is added with its key and fingerprint already set up, no form to fill in.

Before you start

• A Mac or Linux machine that runs herdr 0.7.5 or newer, with Node.js 20 or newer. Windows Hosts can't pair; add them by hand with Windows setup.
• Your iPhone or iPad on the same network as the machine, such as the same Wi-Fi, or connected to the same VPN. Pairing doesn't use the networks in Heeler's Settings > Overlay Networks; you can add those afterwards for use away from home.
• About two minutes: a Pairing Code works once and expires after two minutes.

sudo apt install openssh-server
sudo systemctl enable --now ssh

herdr --version
node --version

herdr plugin install ZingerLittleBee/Heeler --ref plugin --yes

herdr plugin action invoke heeler.pair

After pairing

• Open Agents to see coding Agents across your connected Hosts. Open one to use its terminal or Chat.
• The Host is named after your username and its address. To rename it, open it from Hosts and tap Edit.
• Heeler signs in with this device's Device Key. To pair another iPhone or iPad, repeat steps 3 and 4 on it.
• Pairing a machine that is already in Hosts adds a second entry. Swipe left on the one you no longer need and tap Remove.
• To get notifications on your iPhone or iPad when an Agent needs you (Blocked) or finishes (Done), go to Settings > Notifications, tap Enable Notifications, tap Continue, and allow notifications when iOS asks. Then turn on Notifications for this Host.

Use it away from home

A paired Host has only the addresses you checked, so it connects on the networks where those addresses answer. To reach it from cellular, set up an Overlay Network or a Jump Host, then add the Host's address there as another route: see Reach a Host on several routes. Heeler uses whichever route answers first.

Pair through a port mapping

Run on: Mac or Linux

The popup lists only the addresses on the machine's own network interfaces. When your iPhone or iPad reaches herdr some other way, for example herdr runs in a Docker container whose SSH is published on a port of a NAS, or the machine sits behind NAT, tell the plugin which address and port to put in the code. This needs Heeler plugin 0.6.2 or later; to update it, run the install command from step 2 again.

1. Find the plugin's config directory:

   Terminal

   Copy code

   herdr plugin config-dir heeler

2. In that directory, create pair.json with the addresses (IPs or host names) and the SSH port your iPhone or iPad reaches. For a container published as port 2222 of a NAS at 192.168.1.10:

   Copy code

   {"ssh_port": 2222, "addresses": ["192.168.1.10", "nas.example.com"]}

3. Run herdr plugin action invoke heeler.pair again. The addresses from pair.json come first in the popup and are already checked. The machine's own addresses follow, unchecked.

The port must lead to the OpenSSH server of the machine that runs herdr, because the code carries the fingerprint of its host key under /etc/ssh. If the popup says it could not use pair.json, fix the file, press q, and run the command again. The plugin README describes every field.

Troubleshooting

Pairing errors appear in the popup or in Heeler, not in herdr's plugin log.

Checked against Heeler plugin 0.6.0 on 2026-10-14.