Docs / Pair with Herdr

Pair Lochan with Herdr

One command on the host. One scan on the phone. Nothing to type.

Lochan talks to Herdr, the runtime your coding agents already live in. Pairing lets the phone open an SSH session to a Mac or Linux machine you own, so you can see those agents and type into them from anywhere. Your code and API keys stay on that machine. Herdr is a separate product, not part of Lochan.

What you need

• Lochan on iPhone or iPad (iOS 26 or later).
• A Mac or Linux computer you own. Not WSL: the phone would hit Windows OpenSSH, not the distro.
• Herdr installed on that computer. Pairing still finishes without it, but the phone cannot attach until Herdr is running.
• A network path from the phone to that computer. Same Wi-Fi works. Tailscale is the two-minute version for cellular and away-from-home.

If Herdr is not on the host yet:

1. Run the pairing command

   On the Mac or Linux host, in a terminal:

   curl -fsSL lochan.app/herdr-setup | sh

   The script turns on Remote Login (macOS) or SSH (Linux) if it is off. Your password is needed once for that, and not at all if SSH is already running. It then shows a QR code and waits up to two minutes for the phone.

   Run one setup at a time. A second run on the same machine kills the first QR before you can scan it.

   If Tailscale is installed but not signed in, or not installed at all, the script says so before drawing the code. That code only reaches the machine from the same Wi-Fi until you run it again on a live tailnet.

2. Scan from Lochan

   On the phone, open Lochan, then Herdr in the sidebar. Tap Scan pairing code on the Herdr tour's last page, or from Add Host. Point the camera at the QR on the host's screen.

   Scan from the Lochan app. A camera app only works if it opens the lochan:// link rather than saving a photo.

   The phone makes its own SSH key and keeps the private half in the Keychain. Only the public half is sent to the host. The QR also carries the host's SSH fingerprint, so you are not asked to compare it by hand. The code is single-use and lasts about two minutes.

   When it works, the host prints:

   Authorized key: 256 SHA256:… (ED25519) Done! You can now connect from your phone.

3. Reach the host from anywhere

   The phone SSHes straight to that machine. There is no Lochan server in the middle. Away from home, both devices need a path to each other.

   Install Tailscale on the host and the phone, sign in, then run the pairing command again so the QR uses the MagicDNS name. After that, a blocked agent on your desk can be answered from cellular.

If you cannot scan

Add Host still has a manual form. Copy this phone's public key onto the host, or use Install key on host (Mac password once). Pairing again on a machine you already saved replaces that host's key instead of adding a duplicate.

Troubleshooting

• Can't pair. Install Herdr from herdr.dev first. Run the Lochan setup command on the host, then scan from the Lochan app. Confirm Remote Login is on in System Settings > General > Sharing (macOS), or that OpenSSH is running (Linux).
• Pairing timed out / code already used. Run the command again when the phone is ready. The QR is good for one scan and about two minutes.
• Herdr is not running on this host. Pairing can finish before Herdr is installed. Install it, start it, then pull to refresh in Lochan.
• Can't reach the Mac away from home. The phone needs a path to that machine. Tailscale (or another VPN) is the usual fix. Re-run the setup command after Tailscale is running so the QR picks up the tailnet name.
• WSL. Not supported. Run the command on macOS or a real Linux host.
• A second phone. Run the command once per phone. Each scan installs that phone's own key.
• Still stuck? Email [email protected].

What pairing stores

On the phone: the host address, username, the path to herdr, and this phone's private key in the Keychain. On the host: this phone's public key in ~/.ssh/authorized_keys. The throwaway pairing key is deleted when pairing finishes, times out, or you press Ctrl-C. Traffic goes only to the host you pair, not to Lochan and not to herdr.dev.

Lochan uses Herdr, the runtime coding agents run on. Herdr is not a Lochan product. See also Support and the Privacy Policy.