Troubleshooting

On the computer first:

pairfob doctor

Service:

pairfob service status

Sentences in the UI

Match the English Pairfob string on screen:

You see	Do this first
The computer is offline	Sleep, a closed lid, a dropped network, or pairfob not running. Wake the computer; you do not pair again. Then pairfob doctor
Offline · last connected: … / Can't reach … (the page title on a wide screen)	The only paired computer, or pairfob.com, cannot be reached. Follow the steps on the page; it retries by itself and you do not pair again
Herdr isn't running on the computer	The machine is up, but Herdr quit. Open Herdr; Pairfob recovers automatically
No sessions on … yet	Connected, but there is no session yet — create one or open a terminal on the computer
Enter the full pairing code shown on the computer	Hand entry is 8+6 glyphs
The pairing code is not complete: 14 characters needed	Include the locator
The pairing code is too long: it should have 14 characters	Keep only the 14 the computer shows
That pairing code is spent or expired	pairfob pair again on the computer
That pairing code is incorrect	Use the code being printed now; do not edit the old one
Too many attempts	Wait; do not loop
This Herdr version cannot do that yet	Computer Herdr, not a missing phone button
The computer may already have run that action	Do not double-tap; look at the frame
That session is gone	Back to the list
Another window took over this device's connection	Keep a single Pairfob page
Could not read site config / Could not reach this site	Network or wrong page
Another computer started pairing	Slot stolen; pair on the computer you mean
P2P is temporarily unavailable. Relay remains active	Direct path failed; the session stayed on Relay. To stop retries, set Network route to Relay only
P2P is unavailable on this site	This site has direct paths off; only Relay is available

doctor

Output	Action
Running no	Follow the suggested command: pairfob service install if not installed, pairfob service start if stopped, pairfob service restart if running but not answering, or pairfob run if the service manager is unavailable
Herdr anything but ready	Follow the hint on that line: pairfob setup installs the latest stable Herdr if missing and starts its server when needed. Herdr 0.8+ is required
Origin … not set up	Rerun the installer
Paired 0	pairfob pair
P2P off	This computer is relay-only (PAIRFOB_P2P=0)

Running in a container without a systemd user bus

In a Linux container or Kubernetes pod, systemctl --user may fail with Failed to connect to bus: No medium found. A pairfob.service file can exist even when no systemd user manager is available. Setting XDG_RUNTIME_DIR alone does not start one.

pairfob update can replace the installed binary but cannot restart the daemon through an unavailable service manager. It reports the restart failure; the old process may keep running the previous image. pairfob version describes the installed binary, not that process.

Use pairfob doctor to inspect the running daemon. pairfob service status also checks its PID, version and image through the local admin socket when the service manager fails. It shows the manager error separately and exits nonzero because the service cannot be verified, even if the installed and running images match.

Configure your container entrypoint or external supervisor to run the absolute path to pairfob run (for example, /home/agent/.local/bin/pairfob run). After an update, restart it through that supervisor. For a cron watchdog, pause the watchdog, stop its existing daemon, then let it start the new binary. Keep the same user, HOME, state directory and runtime environment to preserve pairing. If no daemon is running, pairfob run starts it in the foreground. Check pairfob doctor and pairfob service status again after restarting.

Install and enroll

• Do not set PAIRFOB_JOIN_TOKEN or PAIRFOB_JOIN_GRANT
• Checksum mismatch: the script fails closed
• Unsupported OS (Windows): the script refuses
• If ~/.local/bin is not on PATH, pairfob is “not found” even when the service is installed

macOS repeatedly asks for file access

Access to other apps' data and access to Downloads, Desktop or Documents are different permissions. Some app-container consent lasts only for the running process, so restarting the daemon can prompt again. Release builds are signed with a stable Pairfob certificate, so installing a later version keeps those grants. Switching from an older ad-hoc build, or from a different signing identity, can require one new grant. Locally built ad-hoc executables may lose grants on every replacement.

Terminal and chat do not require access to Photos, screen recording, Accessibility or Input Monitoring. File features access the selected workspace; chat and quota features read the relevant Agent's local data. Some quota sources also request separate Keychain authorization.

Current versions read Keychain silently during ordinary quota refresh. If unlocking or consent is required, that source pauses instead of displaying background prompts. Timeouts are reported separately. pairfob doctor shows the executable, its on-disk signing identity, enabled quota sources and recent Keychain results without probing protected folders.

Run pairfob quota authorize cursor on the computer to allow a Keychain prompt (also supports claude and antigravity). Whether access persists depends on your choice in macOS. After changing permissions yourself, use pairfob quota retry cursor to resume silent reads. Wait for the one-minute quota cache to expire before refreshing. Use the same executable as the running service. Development builds without native Keychain support report unavailable.

To read only selected quota sources, install the service with an allowlist:

PAIRFOB_QUOTA_PROVIDERS=codex,cursor pairfob service install

none disables all quota discovery; leaving it unset enables all sources. This affects quota queries only. Service installation takes the current shell's environment, so retain your other service settings when reinstalling it.

On macOS, workspace-wide search and Git discovery skip the home directory and its ancestors. Browsing individual directories still works. Set the session cwd to a specific project for recursive search and Git review. Projects inside Downloads or Documents can still require first-use consent.

If you need continuing access to protected files, you can add Pairfob in System Settings → Privacy & Security → Full Disk Access. Run pairfob service status and use its Executable path (normally ~/.local/bin/pairfob); press ⌘⇧G in the file picker to enter it. Then run pairfob service restart.

Full Disk Access is broader than project access, is optional, and does not grant Keychain authorization. Pairfob does not change system privacy settings. Avoid resetting all privacy grants, which makes other apps ask again too. See Apple's app-data privacy explanation.

Pairing

• Use the code in the current terminal, not a screenshot
• Hand entry is 14 glyphs; missing the locator means the request is not sent
• Scan failures: camera permission, or type instead
• The computer must still be waiting in pairfob pair; Ctrl-C means open a new slot
• Two computers running pair at once steal the slot from each other

Network route

• Default Auto: Relay first, then P2P when a direct path exists; a failed upgrade does not drop the session
• Switching Wi-Fi or coming back online probes immediately and resets the P2P retry timer
• Settings shows why the last direct attempt failed while the session stays on Relay
• Direct path keeps failing: Settings → computer card → Network route → Relay only
• To try a direct path again: Auto, or P2P only for an immediate attempt
• Relay only pauses automatic P2P retries in this browser
• Pairfob does not run TURN; a strict NAT stays on Relay
• If an existing P2P path loses ICE, the session drops back to Relay without disconnecting, then retries the upgrade

Connected but cannot act

• Still on the pairing page means not paired
• If Herdr quit, an open session fails; open Herdr first
• Missing buttons: upgrade and restart the running Herdr
• Path rejected: outside the directories the computer allows

Sleep, lock, lid

• Locked screen, machine still up: should work. Pairfob does not need the desktop unlocked
• Closed lid / sleep: the phone shows The computer is offline. Open the lid or wake it. Do not pair again; the computer stays on the list
• Herdr quit while the machine is awake: Herdr isn't running on the computer
• Pairfob cannot wake a sleeping computer. Details: FAQ

Still stuck

Keep the full pairfob doctor output. Do not paste pairing codes.