Guide

Set up the Relay — from scratch with a Raspberry Pi

For anyone who has never knowingly touched Linux. We’ll set up a Raspberry Pi with the Imager and install the Relay on it — step by step.

approx. 30 min Beginner-friendly Last updated:

This guide assumes you’re starting from zero: no Raspberry Pi, no Linux experience. We’ll go through it together, and wherever you type a command, you’ll read exactly what it does.

Part A — Prepare the Raspberry Pi

Get the hardware ready

You’ll need:

  • A Raspberry Pi 4 or 5 (a Pi 3 works too). Not suitable: the Pi Zero or the oldest Pi with ARMv6.
  • A microSD card (16 GB is plenty) and a power supply for the Pi.
  • A computer (Windows, macOS or Linux) with an SD-card reader, to write the card once.
  • A network connection: an Ethernet cable is easiest, but Wi-Fi works too.

You do not need a screen or keyboard for the Pi — we’ll set it up “headless” (remotely).

Install the Raspberry Pi Imager

The Raspberry Pi Imager is the official tool for writing the operating system to the SD card. Download it onto your computer from raspberrypi.com/software and install it (it’s available for Windows, macOS and Linux). Then put the microSD card into your computer’s card reader and open the Imager.

Raspberry Pi Imager, “Choose device” screen: a list of Pi models with “Raspberry Pi 3” highlighted.
The Imager at the start: first pick your Pi model under “Choose device” (then come “Choose OS” and “Choose storage”).

Choose the operating system

Click “Choose OS” and, under “Raspberry Pi OS (other)”, choose “Raspberry Pi OS Lite (64-bit)”. “Lite” means: no desktop — exactly right, since the Relay runs in the background and needs no screen.

Raspberry Pi Imager, “Choose OS”: the “Raspberry Pi OS (other)” entry is highlighted.
Under “Choose OS”, scroll down to “Raspberry Pi OS (other)”.
Raspberry Pi Imager: “Raspberry Pi OS Lite (64-bit)” is selected.
Then pick “Raspberry Pi OS Lite (64-bit)” — no desktop, just right for the Relay.

Screenshot 1 of 2

Before writing: pre-configure the Pi

This is the most important step. After you pick the SD card, click “Next” — the Imager now walks you through the customisation steps (in the sidebar: Hostname, Localisation, User, Wi-Fi, Remote access). This makes the Pi reachable on first boot without a screen.

Set the following:

  • Hostname: e.g. poolpilot-relay — you’ll use it to find the Pi on the network later.
  • Username and password: remember them well; you’ll log in with them.
  • Wi-Fi: only needed if you’re not using an Ethernet cable — enter the SSID, password and your country.
  • Time zone and keyboard layout: to match your location.
  • On the “Remote access” step (SSH authentication): enable SSH and choose “Use password authentication”. SSH is the remote connection we’ll use to operate the Pi in a moment.
Raspberry Pi Imager, “Choose storage”: the SD-card reader is listed.
First select your microSD card. Click “Next” to reach the customisation steps.
Imager settings, “Hostname”: the field contains “poolpilot-relay”.
Hostname, e.g. “poolpilot-relay” — you’ll use it to find the Pi on the network later.
Imager settings, “Localisation”: Berlin, time zone Europe/Berlin, keyboard “de”.
Time zone and keyboard layout to match your location.
Imager settings, “User”: username “benutzer” and a password are set.
Your choice: “benutzer” and “passwort” are only examples — enter your own username and a strong password, and remember them well.
Imager settings, “Wi-Fi”: SSID “Mein Heimnetz” with a masked password.
Only needed without an Ethernet cable: enter the SSID, Wi-Fi password and your country.
Imager settings, “SSH authentication”: SSH is enabled and “Use password authentication” is selected.
SSH on: Password authentication is enough for this guide. Public-key auth would be more secure but is beyond its scope.
Imager settings, “Raspberry Pi Connect”: the feature is switched off.
You don’t need “Raspberry Pi Connect” — just leave it off. The Relay handles remote access later.

Screenshot 1 of 7

Write the microSD card

Click “Write”. The Imager downloads the system, writes it to the card and verifies it afterwards. This takes a few minutes. When it reports success, you can eject the card.

Imager, “Write image”: a summary of the chosen settings.
The Imager shows a summary of your choices. Click “Write” to start.
Imager warning: “You are about to ERASE all data” with “Cancel” and “I understand, erase and write”.
Careful: The card is erased completely. Make sure the right card is selected, then confirm.
Imager: a “Writing…” progress bar.
The system is written to the card …
Imager: a “Verifying…” progress bar.
… and then verified. Done — eject the card.

Screenshot 1 of 4

Boot the Pi and find it

Put the microSD card into the Pi, connect the network cable (if using Ethernet), then the power supply. The first boot takes a little longer — give it a minute or two.

Now connect from your computer over SSH. Open a terminal (on Windows, “Command Prompt” or PowerShell) and type — using your username and hostname:

ssh user@poolpilot-relay.local

The very first time you connect, SSH asks whether you trust the device — confirm with yes, then enter your password.

Part B — Install the Relay

Run the install command

You’re now on the Pi over SSH. Run the install command:

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

The installer detects your architecture, downloads the matching version, verifies it cryptographically (SHA-256 checksum, and a minisign signature when that tool is available) and sets up a systemd service that starts automatically. Just before it needs system privileges, it prints the exact steps and asks for your password (the same one you set in the Imager).

Part C — Pair and verify

Pair it in the app

Open the PoolPilot app on a phone on the same network. The app discovers the Relay automatically — follow the prompts to pair.

If it isn’t found automatically, show the pairing code on the Pi:

sudo poolpilot-relay show-pairing

This prints a QR code, the same link as text, and a fingerprint for manual entry.

ProCon.IP settings, Remote access section: a “PoolPilot Relay” entry marked “discovered nearby” (labels in German).
In the ProCon.IP settings: the app has found the Relay on the network.
“PoolPilot Relay” screen: a “PoolPilot Relay found” card with a “Set up relay” button, plus “Scan pairing code” and “Enter fingerprint manually” (labels in German).
One tap on “Set up relay” — or pair via pairing code or fingerprint.
PoolPilot app, “PoolPilot Relay” screen: status card with green checkmarks — relay connected, connected, and pool controller reachable (labels in German).
Paired and connected: “Relay connected” and “Controller reachable”, all green.

Check that it’s running

Back in the SSH window, check the status and logs:

systemctl status poolpilot-relay
journalctl -u poolpilot-relay -f

Shortly after boot you should see a line like agent starting version=…. Done — the Relay is running, and the ProCon.IP now has remote access and push. From here the Relay keeps itself up to date; you can just leave the Pi running.

If something goes wrong

All the details — configuration, updates, uninstalling — are in the Relay docs on GitHub.

Relay repository & docs