When something's off
There are only three moving parts — sshd, the daemon, and the hooks — so there's a short list of things that can be wrong.
The app can't find my machine
Discovery is on by default on the host, but it needs Local Network permission on the phone and both devices on the same Wi-Fi. Skip it and scan the QR instead — that works on any network you can reach.
reins serve # discovery is already on reins pair # then scan the QR in Machine → Pair
"Connection refused" when pairing
sshd isn't running, or is on a non-standard port.
# macOS System Settings → General → Sharing → Remote Login: on # Linux sudo systemctl status ssh # non-standard port: put it in the manual form or pass --port to pair
Approvals don't show up on the phone
The hooks aren't installed, the daemon isn't running, or Claude Code was started before the daemon and cached its settings.
reins doctor # shows hook status and whether a phone is connected reins install-hooks # if hooks are missing # then restart Claude Code
I can see the session but can't reply
The agent isn't running inside herdr, tmux or zellij, or the daemon was started with --allow-chat-send=false.
herdr claude # inside the herdr session
"Host key changed" and Reins won't connect
The machine's SSH identity doesn't match what was saved at pairing. That's expected after a reinstall — and exactly what a man-in-the-middle looks like otherwise.
# on the machine itself, compare with what the app shows ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub # if it matches: Machine → Re-pair. If it doesn't: don't.
Everything reconnects every few minutes on cellular
Carrier NAT drops idle connections. Reins backs off 2s→30s and picks up where it left off; nothing on the host is affected.
# optional: keepalives on the host echo "ClientAliveInterval 30" | sudo tee -a /etc/ssh/sshd_config
"That key is passphrase-protected"
The app cannot prompt for a passphrase mid-connection, so it rejects encrypted keys at import rather than failing later at connect time.
# make an unencrypted copy for the phone ssh-keygen -p -N "" -f ~/.ssh/id_ed25519_reins # or skip it entirely — the pairing QR mints a key for you
Dev server preview says nothing is serving
The tunnel is fine; the port on the host is quiet.
# on the host lsof -nP -iTCP:3000 -sTCP:LISTEN # nothing? start your dev server, then Reload in the app
Still stuck? Run reins doctor and paste the output into a GitHub issue. It prints
versions, what's listening, whether the hooks are installed, and whether a phone is connected —
nothing about your projects.