Troubleshooting

On the computer first:

remote doctor

Service:

remote service status

Sentences in the UI

Match the English Remote string on screen:

You see	Do this first
The computer is offline	Sleep, a closed lid, a dropped network, or remote not running. Wake the computer; you do not pair again. Then remote doctor
Offline · last connected: … / Can't reach … (the page title on a wide screen)	The only paired computer, or remote.lzinternal.ai, 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; Remote 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	remote 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 Remote 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: remote service install if not installed, remote service start if stopped, remote service restart if running but not answering, or remote run if the service manager is unavailable
Herdr anything but ready	Follow the hint on that line: remote 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	remote pair
P2P off	This computer is relay-only (REMOTE_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 remote.service file can exist even when no systemd user manager is available. Setting XDG_RUNTIME_DIR alone does not start one.

remote 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. remote version describes the installed binary, not that process.

Use remote doctor to inspect the running daemon. remote 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 remote run (for example, /home/agent/.local/bin/remote 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, remote run starts it in the foreground. Check remote doctor and remote service status again after restarting.

Install and enroll

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

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 remote 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
• Remote 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. Remote 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
• Remote cannot wake a sleeping computer. Details: FAQ

Still stuck

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