Debugging

Almost everything that goes wrong falls into one of three buckets: the daemon is not running, the tunnel is not up, or the install is in the wrong place. This page is the order worth checking them in.

Start here

Four commands that answer most questions

onepilot --version
onepilot serve
onepilot list
onepilot relay status

serve printing a port means the daemon is healthy. It is idempotent, so running it when one is already up just reprints the port.
list shows the live sessions. An empty list with a healthy daemon is normal if you have not opened anything.
relay status shows the host identity, the address it is reachable at, and the tunnel state. Use it when the app cannot see a machine that is clearly running.

Logs

What	Where
Daemon and sessions	`~/.onepilot/bridge.log`
Tunnel, macOS	`~/.onepilot/relay.log`
Tunnel, Linux	`journalctl --user -u onepilot-relay.service`

Follow the daemon log while you reproduce something

tail -f ~/.onepilot/bridge.log

The state files next to that log are readable too. ~/.onepilot/bridge.port holds the port the daemon bound, and bridge.pid holds its process id, which is handy when you want to confirm the thing you are talking to is the thing you just upgraded.

The daemon will not start

The bridge daemon has no service on any platform: it starts on demand and is restarted by stopping it and calling serve again.

Restart it

pkill -f 'onepilot[^ ]* s[e]rve'
onepilot serve

If serve reports that the daemon did not come up in time, read the tail of ~/.onepilot/bridge.log. The usual causes are a home directory the user cannot write to, or an install owned by a different user than the one running the command.

The tunnel is down

Symptom: the server works on your local network but not from outside, or the app shows it as unreachable while the machine is plainly on.

The CLI tries to repair this itself. It checks the tunnel service roughly once an hour and reinstalls it if it has gone missing, so an intermittent problem often clears without you doing anything. When it cannot repair it, it says so and points at re-pairing.

Restarting the tunnel service

Platform	Command
macOS, per user	`launchctl kickstart -k gui/$(id -u)/com.onepilot.relay`
macOS, all boots	`sudo launchctl kickstart -k system/com.onepilot.relay.system`
Linux, per user	`systemctl --user restart onepilot-relay.service`
Linux, system	`sudo systemctl restart onepilot-relay.service`

When re-pairing is the answer

Several messages end with a suggestion to run onepilot pair again. That is not a brush off: pairing re-provisions the host identity, the relay registration, and the boot service in one pass, which is exactly the set of things that goes stale. Re-pairing is safe and does not create a duplicate server.

Common messages

Message	Meaning
no daemon: run onepilot serve first	Nothing is listening. Start it, then retry.
the platform binary package is not installed	npm skipped optional dependencies. Reinstall with `npm install -g onepilot --include=optional`.
this binary was not installed with npm	The upgrade path only knows how to update npm installs. Reinstall it the way it was installed.
this host has no relay identity	The machine was never paired, or its identity was reset. Run `onepilot pair`.
the tunnel is down, last known up	The service stopped. Restart it with the command for your platform above.
pairs over the local network only	The tunnel could not start at pairing time. Pair on the same network for now; see pairing.
autostart is not supported on this platform	The tunnel runs but will not survive a reboot on its own.

Ports and network

The daemon listens on 127.0.0.1 only, near port 24544, walking upward if that one is busy. It is not reachable from another machine and does not need a firewall rule.
The tunnel is an outbound TLS connection on port 443. If outbound 443 is filtered, the tunnel cannot come up, which is worth checking on a locked down corporate network.
SSH is whatever port you told the app about, 22 unless you passed --port when pairing.

When nothing else works

The escalation that resolves most stuck hosts, in order:

onepilot upgrade
pkill -f 'onepilot[^ ]* s[e]rve'
onepilot serve
onepilot pair

Upgrade first, because plenty of reports turn out to be a host running an old build. Re-pairing last, because it re-provisions everything else. If it still fails, get in touch: the tail of ~/.onepilot/bridge.log is the thing to send along.