ParleyPort

ParleyPort

Docker app from junkerderprovinz's Repository

Your own relay for apps that pair their instances.

Overview
Your own relay for apps that pair their instances. Instances on the same network talk directly, but two instances on different networks, behind NAT or a firewall that lets nothing in, need a third point both can dial out to. ParleyPort is that point. It groups the connections that share a relay key and passes their messages on, sealed end to end with a key that never leaves your instances, so it cannot read what it carries. You only need it if you want your own relay. The apps it serves use a project relay by default, and an instance that is already reachable from outside can serve as the relay itself. ParleyPort is for running your own without putting the app itself on the open internet: a few megabytes, no accounts, no database, nothing stored. Plain mode listens on port 8760 for a reverse proxy in front, which must allow WebSocket upgrades on /relay/connect. Set a domain and map port 443 instead, and it fetches and renews its own Let's Encrypt certificate, with port 80 left closed. Then enter the address under Settings, Pairing, Relay, Own relay on every instance of the group.

ParleyPort

Build  Lint  Docker Pulls  Image Size  Arch  Go  Unraid  License: AGPL-3.0

ParleyPort is a relay for apps that pair their instances. When two of your instances sit on different networks and neither can reach the other, both dial out to ParleyPort and meet there. It passes their messages on without being able to read them, and it runs as one small container that keeps no accounts and stores nothing.


Table of Contents

  1. Download
  2. Support
  3. What it looks like
  4. What it does
  5. Getting started
  6. For app authors
  7. How AI is used here

1. Download

Server

Install from Unraid's Community Applications   Install from the MOS Hub   Download the docker-compose file   Download the source archive


2. Support

A one-knight job: I build it, keep it running, work through the issues and add what people ask for, until nothing is missing. It is free, with no accounts, no telemetry, no ads and no paid tier. No asterisk anywhere. Nothing readable ever leaves your own walls. Forged on evenings and weekends, with heart and stubbornness.

If it has earned a place on your server or computer, toss a coin to your knight: it helps cover the costs and keeps the project alive. It also makes this knight's heart beat a little faster. Three ways below, whichever suits you.

Buy me a coffee   PayPal   Donate with crypto


3. What it looks like

Its address shows a short page that says what it is, and that is all of ParleyPort a browser sees. The rest is the relay setting in your apps and the container's log.

An app's relay settings with Own relay selected and the address of a ParleyPort relay filled in
An app's relay card pointing at your own ParleyPort

A terminal showing the log of the ParleyPort container: the start banner and the line that it is listening on port 8760
The container's log after a start: ready and listening


4. What it does

Apps that use ParleyPort pair their instances with twelve words. Instances on the same network talk directly. Instances on different networks, behind NAT or a firewall that lets nothing in, need a third point both can dial out to, and that point is a relay. ParleyPort groups the connections that present the same relay key, a hash of your twelve words, and passes their messages between them.

  • It cannot read what it carries. Every message is sealed with AES-256-GCM under a key derived from the twelve words, and the routing fields are bound into the seal, so a relay can neither open a message nor send it to another instance.
  • It keeps nothing. No accounts, no database and no record of who connects. Client addresses are left out of its log. What any relay can still see is which instances talk and when, which is the reason to run your own.
  • It brings its own certificate. Give it a domain and it fetches and renews a Let's Encrypt certificate on port 443, with port 80 left closed. Without a domain it serves plain HTTP on port 8760 for a reverse proxy in front.
  • It is small. A few megabytes for amd64 and arm64, fine on a small VPS while your instances stay at home.

You probably do not need it: these apps use a project relay by default, and an instance that is already reachable from outside can often serve as the relay itself. ParleyPort is for your own relay without putting the app itself on the open internet.


5. Getting started

On Unraid, install ParleyPort from Community Applications. Anywhere else, for a reverse proxy in front:

docker run -d --name parleyport -p 8760:8760 junkerderprovinz/parleyport:latest

The proxy sends /relay/connect to port 8760 with WebSocket upgrades allowed (in Nginx Proxy Manager, switch on Websockets Support). Set PARLEYPORT_PUBLIC_URL to the address your instances dial, for example https://relay.example.org. If the proxy runs in another container or on another machine, also name it in PARLEYPORT_TRUSTED_PROXIES, for example 172.18.0.5. Failed handshakes then count against the caller and not against the proxy that everyone comes through.

To let ParleyPort handle TLS itself instead, set PARLEYPORT_DOMAIN, forward port 443 to it and keep its certificates on a volume:

docker run -d --name parleyport -p 443:443 \
  -e PARLEYPORT_DOMAIN=relay.example.org \
  -v /path/to/parleyport:/var/lib/parleyport \
  junkerderprovinz/parleyport:latest

Then, on every instance of the group, open Settings, Pairing, Relay, Own relay and enter the address, for example https://relay.example.org. The twelve words stay the same, so switching relays needs no new pairing. A relay that ran from the old knightloader-relay image can switch images as it is, since ParleyPort still reads its KL_RELAY_* variables.

Other Docker hosts

compose.yaml runs ParleyPort on any Linux server with Docker. Put it in a folder of its own and start it with docker compose up -d. The folders are created next to the file.

  • Synology: in Container Manager, create a project from the file (DSM 7.2 or newer).
  • Proxmox: run it in a VM or an LXC container that has Docker.
  • MOS: install ParleyPort from the MOS Hub.

6. For app authors

The other half of ParleyPort is the kit, the client side of the protocol as a Go module of its own. An app that pairs its instances imports it and gets the twelve words, the member keys, the relay client, the group that finds its members on the network or over the relay, and the fortress that puts all of a household's apps under one phrase.

go get github.com/junkerderprovinz/parleyport/kit@latest

The kit has a version line of its own. The server's tags are vX.Y.Z, the kit's are kit/vX.Y.Z, so an app moves to a new kit without waiting for a new relay. kit/README.md lists the packages, and kit/CHANGELOG.md says what each version brought.

A plugin without Go code takes part through the two helpers attached to every release, built for linux/amd64 and arm64. fortress joins a fortress, lists the members, reads their status, asks one of them for an action and takes one out. notify sends a message to the channels in a file and shows and saves those channels with every secret masked. Check what you download against helpers-sha256sums.txt:

base=https://github.com/junkerderprovinz/parleyport/releases/latest/download
curl -fsSL -O "$base/fortress-linux-amd64" -O "$base/helpers-sha256sums.txt"
sha256sum --check --ignore-missing helpers-sha256sums.txt

7. How AI is used here

One knight builds this, and AI is one of the tools I work with, the same way I work with an editor or a compiler. It helps me write code and documentation and it checks my work, and that saves me a good many evenings. It does not make the decisions, though. I read and understand everything before it ships, and if something here breaks, that is on me and not on the tool.

You do not have to take my word for it. The code is open and every release note is written by hand. The issue tracker shows how problems actually get handled, including the ones I got wrong the first time. If you find something that is not right, open an issue and I will look at it.


Bugs, ideas or feature requests? Please open a GitHub issue.


The name ParleyPort, its logo and its branding are not covered by the AGPL-3.0 licence of the code: a fork needs its own name and look.

Categories

Download Statistics

803
Total Downloads

Related apps

Links

Details

Repository
junkerderprovinz/parleyport:latest
Last Updated2026-10-23
First Seen2026-10-02

Runtime arguments

Network
bridge
Shell
sh
Privileged
false
Extra Params
--restart unless-stopped

Template configuration

Relay Port (plain)Porttcp

Plain HTTP for a reverse proxy in front. Point the proxy at this port and allow WebSocket upgrades on /relay/connect. /health answers with the status and version.

Target
8760
Default
8760
Value
8760
Relay Port (TLS)Porttcp

Only with a domain set below. Enter the host port your router forwards 443 to. Leave it empty in plain mode, and keep it off 443 if the Unraid web interface already uses that port.

Target
443
DomainVariable

Your relay's domain, for example relay.example.org. With it set, ParleyPort serves TLS on 443 inside the container and gets its own Let's Encrypt certificate through port 443 alone. Several names can be given, separated by commas, to keep an old name working during a move. Leave it empty for plain mode behind a proxy.

Target
PARLEYPORT_DOMAIN
Public URLVariable

The address your instances dial, for example https://relay.example.org, or several separated by commas. An instance may prove who it is only to the relay it names when it connects, so set this in plain mode behind a proxy. In domain mode the names above already count and this can stay empty.

Target
PARLEYPORT_PUBLIC_URL
Trusted proxiesVariable

For a reverse proxy in another container or on another machine: its address, for example 172.18.0.5, or a range no wider than a /28 (IPv4) or /124 (IPv6). Separate several with commas. Failed handshakes then count against the caller and not against the proxy everyone comes through. Left empty, only a proxy on the same host is trusted; none trusts no proxy at all.

Target
PARLEYPORT_TRUSTED_PROXIES
DataPathrw

Holds the certificates in domain mode, so a restart does not ask Let's Encrypt for a new one. Stays empty in plain mode.

Target
/var/lib/parleyport
Default
/mnt/user/appdata/parleyport
Value
/mnt/user/appdata/parleyport