Relay docs

Help & commands

Most problems have one of three causes — the Relay isn’t running, the phone and the Relay aren’t on the same network, or the app still remembers an old identity of the Relay. Here’s how to find out which, plus every command you need for it.

Last updated:

You type the commands on this page on the device the Relay runs on — directly or over SSH. If your Relay runs in Home Assistant, the matching steps are on the Home Assistant page.

The app can’t reach the Relay

  1. Is it running? systemctl status poolpilot-relay should show active (running). If not, restart it with sudo systemctl restart poolpilot-relay and look at the logs (below).
  2. Same network? At home the app finds the Relay over your local network. Your phone has to be on the same Wi-Fi — not on guest Wi-Fi and not on mobile data.
  3. “Unreachable” after a factory reset? A factory reset gives the Relay a new identity that no longer matches what the app remembered. It then looks unreachable even though it’s fine. Remove the Relay in the app and pair it again (see Pairing & household).

Remote access paused even though the Relay is running? Then look at When Pro lapses and the section below it.

Look at the logs

systemctl status poolpilot-relay        # running? since when?
journalctl -u poolpilot-relay -f        # live logs, stop with Ctrl+C
journalctl -u poolpilot-relay -b        # everything since the last boot
journalctl -u poolpilot-relay-updater   # what the update helper did

The installer makes sure these logs survive reboots. Shortly after starting you should see a line like agent starting version=….

Repeated mDNS log lines

Seeing lines with Recursion Available bit MUST be zero and (RFC6762 18.7) on every start? That’s normal and harmless. They come from the library the Relay uses to announce itself on the network; the packet it sends is correct and discovery works. Newer Relays hide these lines. To debug discovery, bring them back with MDNS_VERBOSE_LOGS=1 in the config file — in Home Assistant with the Additional mDNS logs toggle.

All commands at a glance

Day to day you need none of them — systemd keeps the Relay running, and everything else happens in the app.

Command What it does
sudo poolpilot-relay show-pairing Shows the pairing code: QR code, the link as text, and the fingerprint. Changes nothing.
sudo poolpilot-relay show-recovery Shows a one-time recovery code to take the owner role back. Valid for a few minutes.
poolpilot-relay version Prints the installed version (also --version, -v).
poolpilot-relay help Lists the commands and options (also --help, -h).
systemctl status poolpilot-relay Is the Relay running, and since when?
sudo systemctl restart poolpilot-relay Restarts the Relay, e.g. after a config change.
sudo systemctl stop poolpilot-relay Stops the Relay.
sudo systemctl disable --now poolpilot-relay Stops the Relay and keeps it from starting at boot.

The version that’s actually running is shown in the PoolPilot app too — or in the start line of the log:

journalctl -u poolpilot-relay | grep "agent starting"

What the installer puts on the device

  • /usr/local/bin/poolpilot-relay — the Relay itself, started by the poolpilot-relay systemd service.
  • /usr/local/bin/poolpilot-relay-updater — the update helper. systemd starts it when an update is ready; you never run it by hand.
  • /etc/poolpilot-relay/config — the config file.
  • The systemd units poolpilot-relay.service, poolpilot-relay-updater.service and poolpilot-relay-updater.path in /etc/systemd/system/.

Update or repair

Running the installer again brings the Relay to the current version and repairs a broken install. Your configuration and pairing stay as they are:

curl -fsSL https://get.poolpilot.eu/install.sh | bash

Factory reset

You start a factory reset in the PoolPilot app. Two conditions apply, on purpose: only the owner can do it, and only while their phone is on the same network as the Relay — not while you’re away.

The reset wipes the pairing and the identity, and the Relay restarts with a fresh identity. It’s unpaired afterwards: remove the old entry in the app if it’s still there, and pair it again as if it were new.

Remove the Relay

To uninstall the Relay completely from a Raspberry Pi or Linux box:

# stop and disable the service (and the update watcher, if present)
sudo systemctl disable --now poolpilot-relay
sudo systemctl disable --now poolpilot-relay-updater.path 2>/dev/null || true

# remove the programs, systemd units, config and state
sudo rm -f /usr/local/bin/poolpilot-relay /usr/local/bin/poolpilot-relay-updater
sudo rm -f /etc/systemd/system/poolpilot-relay.service \
           /etc/systemd/system/poolpilot-relay-updater.service \
           /etc/systemd/system/poolpilot-relay-updater.path
sudo rm -rf /etc/poolpilot-relay /var/lib/poolpilot-relay /var/lib/poolpilot-relay-updater
sudo systemctl daemon-reload

The installer also made the systemd journal persistent. To undo that too (optional):

sudo rm -f /etc/systemd/journald.conf.d/95-poolpilot-persistent.conf
sudo systemctl restart systemd-journald

In Home Assistant you simply uninstall the app — read the note about your data first.

Still stuck?

Open an issue in the Relay repository and attach your logs — redact anything sensitive first. Or drop by the help page.

Relay repository & docs