LibrePortal Connect turns a LibrePortal server with a public address into a relay, so servers at home that can't open a port on their router stay reachable by their owners. It only passes along traffic that's already encrypted, and never holds a key.
On this page
Good to know before you install
A relay is not a VPN of its own and is not LibrePortal's built-in private network: it only forwards traffic that is already encrypted, and never holds a key.
At a glance#
- What it is
- Relay for Servers Behind NAT Networking · made by the LibrePortal project
- Where it opens
- No web page It works in the background
- Updates
- When you choose New versions wait for you to press Update
- Backups
- Included Part of the daily backup when that's switched on
- Copies
- One per server
What it's good for#
This is the other half of LibrePortal Connect. That page is for the person whose server sits behind a router they can't open; this app is for whoever runs the relay those servers connect out to. Most people install it on a small VPS, for their own home server and perhaps a few friends' as well.
You only need it if you want your own relay. If a friend already runs one, you don't install anything: they give you a join code and you use it on Admin → Connect on your own server, as that page explains.
Why run your own
A relay can't read what passes through it, but it can see that a server and its devices are talking, when, and how much. On your own relay, you're the only one who sees even that.
Before you install#
Install it on a server the internet can reach directly: a VPS, or a machine at home with a port you can forward. A relay behind another router is no use, because nobody could reach it.
It needs one port, UDP 51900, open to the internet. LibrePortal opens it in the server's own firewall. If your VPS provider has a firewall of its own in their control panel, allow UDP 51900 there too.
Signing in#
There's nothing to sign in to. The relay has no web page and no accounts. Everything is done from its Tools tab, which talks to the relay from inside its container using a token the relay made for itself when it first started. That token never leaves the container, and the relay's admin port is private, so only your trusted places could even knock on it.
Letting a server use it#
- On the relay's page, go to Tools and run New Enrolment Code. Put a note saying whose server it's for, so you can tell them apart later, and how long the code should last (24 hours unless you say otherwise, up to 30 days, written like
30m,24hor3d). - The task output shows the code, starting
lpc1-, and the relay address to go with it. Send both to the server's owner privately. Anyone holding the code can join one server to your relay. - They enter the address and code on Admin → Connect on their server. It works once; after that the code is spent.
List Servers shows every server that has joined, with its id, your note, whether it's connected right now and how many devices are using it. Remove Server takes one of those 16-character ids and cuts that server off at once. It would need a fresh code to come back.
You can make codes from the command line as well, which is handy over SSH:
sudo -u libreportal libreportal app tool connect new_code "label=Sam|valid_for=3d"
sudo -u libreportal libreportal app tool connect list_servers
Giving the relay a name#
Out of the box, new codes point servers at this server's public IP address. That works, but if the VPS ever moves to a new address, every server using the relay loses it. A name is kinder: create a DNS record such as connect.example.com pointing at the relay, then set Public Address to that name. New codes will carry it from then on.
Public Address lives in the app's config file rather than on the Config tab for now. Change it by reinstalling with the value, which keeps everything else:
sudo -u libreportal libreportal app install connect 'CFG_CONNECT_PUBLIC_HOST=connect.example.com'
Do this before you hand out any codes. A server keeps the relay address it joined with, and its devices' VPN configs name that address too, so a new Public Address only reaches servers that join from then on. To move a server that already joined, make it a fresh code; its owner uses Change on their Admin → Connect page to join again with it, then adds their devices again so their configs carry the new address.
Limits#
Three settings keep one relay fair when several households share it. They live in the config file too, and change the same way as Public Address (see Settings in the config file).
Most Servers is how many servers may join, 100 to start with. Devices Per Server is how many devices can use one server through the relay at the same time, 64. Speed Limit (Mbit/s) caps each server's traffic, each way, at 25 Mbit/s; 0 removes the cap.
That speed limit is worth a thought. It's plenty for opening apps, syncing files and listening to music, but a household streaming films from Jellyfin through the relay will feel it. If it's only your own servers on the relay, you can raise it or set it to 0.
Good to know#
- It isn't a VPN. The relay only forwards WireGuard traffic between a server and its devices. Each server still runs its own LibrePortal VPN, with its own devices and rights; the relay just changes the route.
- Updates wait for you. The relay is pinned to one exact release, and nothing changes until you press Update, which only fetches that same release again; it can't move the relay to a newer one yet. Servers using it notice a restart as a pause of a few seconds.
- Backups matter here. The relay keeps one small thing: the list of servers that have joined, and codes not yet used. It's in the backups, and if you lost it every server would need a new code.
- It's light. No database, no web page, and nothing it passes along is stored. A small VPS can run it alongside other apps.
- One per server. Every server and device reaches the relay on the one UDP port, so a second copy would have nowhere to listen.
Addresses and ports#
LibrePortal Connect has 2 ports. LibrePortal picks a free port number for each when you install, so yours will differ from anyone else's. The Config tab's Network section shows them, and the app's Open button uses the right one. "Anyone" means it's reachable from wherever your server is reachable; you can make it private later.
| What it is | Who can reach it | With a domain |
|---|---|---|
| Relay (devices and home servers connect here) UDP | Anyone | Port only |
| Admin API (enrolment codes; keep private) TCP | Trusted places only | Port only |
Settings#
In its config file#
LibrePortal Connect's own settings aren't on the Config tab yet. They live in the app's config file, described here so you know they exist. How to change them.
| Setting | What it does | Starts as |
|---|---|---|
NameCFG_CONNECT_DISPLAY_NAME |
What this app is called on your dashboards. Leave empty to use its usual name | Empty |
Show on the LibrePortal DashboardCFG_CONNECT_SHOW_ON_DASHBOARD |
Whether this app gets a shortcut on the front page of the LibrePortal WebUI, separate from any Dashy dashboard Choices: true, false |
false |
Public AddressCFG_CONNECT_PUBLIC_HOST |
The name servers use to reach this relay, such as connect.example.org (point its DNS record here). Empty shows this server's public IP | Empty |
Most ServersCFG_CONNECT_MAX_SERVERS |
How many LibrePortal servers may enrol with this relay | 100 |
Devices Per ServerCFG_CONNECT_MAX_DEVICES |
How many devices may use one server through the relay at once | 64 |
Speed Limit (Mbit/s)CFG_CONNECT_RATE_MBIT |
Per server, each way; 0 means no limit | 25 |
Tools#
LibrePortal Connect's Tools tab has 8 buttons for jobs you'd otherwise need a terminal for. Each one runs as a task, so you can watch it on the Tasks page and read what it did. More about Tools.
Is the relay up, how many servers are joined and online, and how many devices are using it now.
Make a one-time code that lets one LibrePortal server use this relay. It includes this relay's address, so its owner pastes it on Admin → Tools → Connect and presses Join.
Every enrolled server: its id, note, whether it is connected now, and how many devices are using it.
Cut a server off this relay at once. It would need a new code to come back.
Codes that have been made but not used yet, and when each stops working.
Make an unused code stop working.
Keep a server joined but carry none of its traffic until you resume it. Its devices stop working meanwhile.
Carry a paused server's traffic again. Its agent reconnects within a minute.
Works with#
These are the other apps LibrePortal Connect knows how to work with. Once it's installed, its page shows the same list with whether each one is connected. How this works.
- Grafana: Shows dashboards for the apps that have one. works with every app
- Prometheus: Collects metrics from the apps that can export them. works with every app
- Uptime Kuma: Watches your apps and shows when one goes down. works with every app
Privacy and security#
All clear Connect is LibrePortal's own relay and sends nothing anywhere itself. If you use someone else's relay they can see that your devices are talking, so you can run your own.
What leaves this server#
- A relay carries traffic between your devices and your servers, so whoever runs it can see connection details such as addresses and timing, not the contents
What LibrePortal turns off#
Nothing needed switching off.
Licence: AGPL-3.0 (repo LICENSE). Audited: 21 October 2026. See the privacy of every app and the Promise.
Sources#
Under the hood#
- It runs this image:
git.libreportal.org/libreportal/libreportal-connect:0.2.0@sha256:7d4312a3446cf1a5c057d17635019995e39e0f5675fe9f271561a61c6992d886. The version is pinned, and moves only when you update it. - It can sit behind Authelia's sign-in once Authelia is installed.
- Its own project and documentation: git.libreportal.org/LibrePortal/LibrePortal-Connect
Ports, settings, tools and connections on this page are read from LibrePortal v0.10.97's app catalogue each time the guide is built.