Troubleshooting

Nearby Shows Nothing

• Allow Local Network for pocketty in iOS Settings → Privacy & Security → Local Network. Without it, the App shows a note under Nearby.
• Put the phone on the same Wi-Fi as the computer. Nearby uses Bonjour, which stays on the local network.
• On a Mac, turn on Remote Login in System Settings → General → Sharing.
• To show up with a code, the daemon must run, Tailscale must be up, and POCKETTY_ADVERTISE must not be off. Check with pocketty status.

You can always type the host’s address by hand instead.

“Cannot reach” When I Send My Key

• Tailscale must run on the phone and the host, signed in to the same account.
• The daemon must run on the host. Check with pocketty status.
• The daemon listens on port 7450 on Tailscale addresses only. A Tailscale ACL that blocks that port blocks code setup.

The Code Is Not Accepted

• A request lasts 2 minutes. Tap Try again on the phone for a new code.
• The Mac alert and pocketty approve give you five tries. After that, the request is denied.
• On a server, run pocketty approve and type the code there.

Cannot Connect

The host screen shows the reason under Cannot connect.

• Host key changed: see When a Host Key Changes.
• Sign-in refused: the host does not have your key. Run the setup command again, or use a code.
• Timeouts: check the address and port, and that Tailscale is up on both ends.

Tap Try again after you fix the cause.

“herdr is not installed on this host”

pocketty looks for herdr with $SHELL -lc 'command -v herdr'. Run that on the host. If it prints nothing, add herdr’s folder to PATH in your login profile (~/.zprofile or ~/.profile), then pull down on the host screen to refresh.

Notifications Do Not Arrive

Work through these in order:

1. Settings → Notifications in pocketty. Push Notifications must be on. If it does not stay on, allow notifications in iOS Settings → pocketty.
2. On the host, pocketty devices should list your phone, without paused.
   • Your phone is not in the list: connect to the host once from the App. If it is still not there, the App can’t find pocketty on the PATH of a login shell or in ~/.local/bin. Run the install command on the host.
   • Your phone shows paused: turn on Push Notifications in pocketty, then connect to the host once.
3. On the host, pocketty status should show herdr and its sessions. The daemon only watches herdr.
4. Check that herdr sees the agent: herdr agent list. An agent that herdr can’t recognize has no state, so it never triggers a notification.
5. If only done is missing, check whether herdr showed that tab on your desktop. pocketty sends no done notification then. See When you get one.
6. Check Focus and Do Not Disturb on the phone.
7. Look at the daemon’s log:
   • Linux: journalctl --user -u pocketty -f
   • macOS: tail -f ~/Library/Logs/pocketty.log
   • Homebrew: tail -f "$(brew --prefix)/var/log/pocketty.log"
   • Anywhere: stop the service, then run POCKETTY_LOG=debug pocketty daemon in a terminal to watch it live.

If you see a notification that says only pocketty: Agent update, the phone could not open the seal. Remove the pairing with pocketty unpair, and connect again from the App to pair fresh.

A Pane Says “Released”

pocketty lets a Pane go when you leave the App, so your desk gets its size back. Tap the terminal to take control again.

Still Stuck

Write to hello@pocketty.app with your device, the iOS version, what you tried, and the output of pocketty status if the daemon is involved. Never send private keys.