Documentation

Pair a phone

Pairing gives one phone its own credential for one computer, and teaches the phone that computer’s exact certificate. There are two ways to do it, and two levels of access.

Nearby: type a code

When the bridge was started with herdr-remote up (or serve --discoverable), phones on the same network list it under On this network. Tap Pair, and a 6-digit code appears on the computer: as a desktop notification, as a Herdr notification and in the terminal running the bridge. Type it on the phone.

Computers found on this network, each with a Pair button
Computers on this network
Code entry with the fingerprint the computer also shows
Enter the code and compare the fingerprint
  • A code expires after two minutes or five wrong tries.
  • Both screens show the first eight characters of the certificate fingerprint. If they differ, cancel: something else answered on your network.
  • Phones paired this way get the access set in the console under Access for phones paired with a code (control by default).

Nearby pairing trusts your network for the first contact

Someone able to impersonate your computer on the same network during that minute could stand in the middle; the fingerprint check is how you notice. On a café, hotel or office network, use a QR invitation instead, and turn advertising off with --no-discovery.

QR invitation

Run this on the computer, in a terminal only you can see:

Terminal
herdr-remote pair --scope control --qr

In the app choose Connect a computer (or + → Pair a computer), scan the QR code, check the address and connection method it shows, name the device and pair. The QR code carries the computer’s address, its full certificate fingerprint and a one-time code, plus the relay route if the bridge has joined one.

  • --scope read|control
    Access for the new device. The default is read.
  • --ttl 300
    Seconds the invitation stays valid, 1 to 3600. The default is five minutes.
  • --qr
    Draw the QR code in the terminal as well as printing the link.
  • --json
    Print the invitation as JSON, to paste into the app instead of scanning.
  • --no-relay
    Leave the relay route out, for a direct-only invitation.

The web console can show the same QR code with a read or control choice and a lifetime.

An invitation is a secret

Anyone who scans it before it expires can pair. It works once; don’t paste it into chat, screenshots or support requests. Make a new one if it expired or was used.

Read or control

  • Watch panes and agents live
    Read: Yes
    Control: Yes
  • Agent history, files, Git changes
    Read: Yes
    Control: Yes
  • Type, send prompts and voice notes
    Read: No
    Control: Yes, while it holds control of that pane
  • Create workspaces and tabs, start agents, close panes
    Read: No
    Control: Yes

A control device is as powerful as a shell on your computer as your user. Give control only to your own devices; a read device suits a tablet on the desk or a teammate looking over your shoulder.

Taking control of a pane

Typing into a pane needs a short control lease for that pane, tied to the program running in it. Opening a terminal takes it automatically if your device has control access (turn off Fit terminals to this screen to only watch). Only one device controls a pane at a time; taking over from another device is a separate, explicit action. Leaving the pane, or the app staying in the background for about 20 seconds, releases control, and keystrokes are never replayed after a dropped connection.

Observing label with a Take control button

List and revoke devices

Terminal
herdr-remote devicesherdr-remote revoke --device 0821ea58-c654-4dce-9346-01206ea81d9e
herdr-remote devices
[  {    "id": "0821ea58-c654-4dce-9346-01206ea81d9e",    "name": "Example iPhone",    "scope": "control",    "createdAt": 1793433255523,    "revokedAt": null  }]

Revoking cuts the device off at once, including live sessions and any control it holds. A relay started with --personal-only refuses it too. The console has a Revoke button per device. On the phone, Forget in Connections removes the saved credential locally; it does not revoke it on the computer, so revoke lost phones from the computer.

WhatsApp