Pair with a Pairing Code

A Pairing Code is a QR code your Host shows so you can add it to Waycar in one scan. Waycar makes your SSH key on the device, adds it to the Host, and pins the Host’s key from the code, so there is no “trust this host?” prompt.

Show a Pairing Code on your Host

The install command offers to show one when it finishes. Press Return to say yes. To pair another device later, run the install command again, or:

• On herdr, open herdr’s actions and choose Pair a mobile device, or run herdr plugin action invoke waycar.pair. herdr must be running. The code opens in a popup in the herdr window, not your terminal.
• On tmux, run waycar pair. The Pairing Code shows right in the terminal.

First the popup, titled Pair a Waycar device, lists the Host’s addresses. One likely address is already checked, so Return is often enough. Otherwise check the ones your phone can reach, then press Return.

Key	Action
up/down or j/k	Move
space	Check or uncheck an address
a	Check all
Return	Confirm and show the code
q, Esc or Ctrl-C	Close the popup

Closing the popup cancels the code, so keep it open until Waycar finishes. On the full-size QR, any key except c closes it; on the compact QR, only q, Esc or Ctrl-C.

Scan it in Waycar

1. In Waycar, tap Scan to Pair. With no Host yet, it’s on the Add Your First Host screen.
2. Point the camera at the Pairing Code on your Host.
3. Waycar reads the code, reaches the Host, enrolls this device, and verifies the new key. Your agents appear.

Can’t scan? Press c on the Host. On a Mac that copies the code; on Linux it shows the code so you can select and copy it. Then tap Paste Pairing Code in Waycar.

What happens on the Host?

When your device enrolls, the Host shows Device paired with the key’s fingerprint. If that wasn’t you, press r to revoke the device.

herdr and tmux

Pairing works the same on both; only where the code appears differs. On a Host set up for tmux, the install command prints a line for ~/.tmux.conf that binds a key to pairing. When ~/.local/bin is on your PATH, it is:

bind W display-popup -E "waycar pair"

Otherwise it uses the full path to waycar, so copy the printed line.

Troubleshooting

• “Pairing Code expired”. A code lasts two minutes. Press Return on the Host for a new one.
• The QR doesn’t fit. The popup draws a compact QR when it can. Otherwise zoom out, enlarge the window, or press c and paste the code.
• Camera Access Needed. Tap Open Settings and allow camera access, or tap Add Manually.
• Scanning Unavailable. This device can’t scan QR codes. Tap Paste Pairing Code, or add the Host by hand.
• My SSH server isn’t on port 22. A Pairing Code always uses port 22. Add the Host by hand and enter its Port.
• Pairing still fails on herdr. Check the Waycar plugin with herdr plugin list --plugin waycar and its errors with herdr plugin log list --plugin waycar --limit 20. See Notifications don’t arrive.

Messages in Waycar

Try Again reuses the same code. When Waycar offers only Scan Again, show a new code on the Host first.

Message	What to do
“The Host did not answer at any of its addresses.”	Join the Host’s network or VPN, then try again with the same code. See Can’t connect to a Host.
“The Host rejected this Pairing Code.”	Codes work once and stop when they expire or the popup closes. Show and scan a new code.
“The Host has no pairing in progress for this code.”	Show a new code and scan it.
“That QR code is not a herdr Pairing Code.”	Scan the code the Host’s pairing popup shows.
“This Pairing Code uses version …, which this app does not understand.”	Update the app and the Waycar host tools so they match. See Update Waycar on your Host.
“The Pairing Code could not be read.”	Show the code again on your Host and scan again.
“The Host did not accept this device’s key.”	Try again. If it keeps failing, update the app and the host tools.
“The Host refused Enrollment (…).”	Update the app and the host tools, then show a new code.
“This device’s key never reached the Host.”	Try again with the same code.
“Enrollment did not complete, likely a network hiccup.”	Try again with the same code.
“This device was enrolled, but the verifying reconnect did not get through.”	Try again to finish with the enrolled key.
“The Host did not accept the Device Key, so it is not authorized there yet.”	Add this device’s authorized_keys line on the Host, or show a Pairing Code on your Host instead.

Messages on the Host

Message	What to do
Pairing cannot start: “No SSH host key found under /etc/ssh.”	On a Mac, turn on Remote Login in System Settings › General › Sharing. On Linux, run sudo ssh-keygen -A. Then start pairing again.
Pairing cannot start: “No routable network address found.”	Connect the Host to a LAN or VPN and retry.
“Select at least one address.”	Check an address with space before you press Return.
Could not revoke the Device Key	Remove the enrolled line from ~/.ssh/authorized_keys on the Host by hand.