Skip to content
minip2p
Esc
↑↓navigate↵open⌘Jpreview

Host a relay server

Install and run the minip2p circuit relay on a Linux server.

The relay server runs as one process and listens on TCP and QUIC over IPv4 and IPv6. By default it uses port 19876 and falls back to whichever address family the host supports.

To try relaying without a server, use the project’s public relay.

You need a Linux x86-64 or ARM64 server with a public IP address. Allow inbound TCP and UDP traffic on port 19876. TCP carries the TCP transport; UDP carries QUIC.

Install the relay

The installer selects the archive for the host architecture, verifies it with the release’s SHA256SUMS, and installs the executable in /usr/local/bin:

curl -fsSL https://minip2p.com/install/relay.sh | sh

The executable is statically linked against musl, so it runs whatever the host’s glibc version. Hostnames passed to --tcp or --quic resolve through musl’s resolver, which skips NSS modules and has no DNS-over-TCP fallback; pass IP addresses if you depend on glibc name resolution.

Set MINIP2P_INSTALL_DIR to install without root, or MINIP2P_VERSION to select a release:

curl -fsSL https://minip2p.com/install/relay.sh | \
  MINIP2P_INSTALL_DIR="$HOME/.local/bin" sh

Install the service

The built-in service command expects systemd and the standard administration tools under /usr/bin and /usr/sbin. On other layouts, use the foreground command below or install an equivalent unit manually.

Install and start the relay under systemd with your public hostname:

sudo minip2p-relay service install --hostname relay.example.com

The command creates a dedicated system user, stores the identity at /var/lib/minip2p-relay/identity.key, writes the relay’s settings to /etc/minip2p-relay/relay.toml, installs a systemd unit that runs minip2p-relay --config /etc/minip2p-relay/relay.toml, and starts it. It will not replace an existing identity. To keep an identity from a manual installation, import it on the first run:

sudo minip2p-relay service install \
  --hostname relay.example.com \
  --import-key "$HOME/.local/share/minip2p-relay/identity.key"

Replace relay.example.com with your hostname. Give it A and AAAA records when the server has both address families. Allow inbound TCP and UDP port 19876 in the host firewall and cloud security group. If you manage DNS through Cloudflare, keep these records in DNS-only mode. Cloudflare Tunnel and the standard Cloudflare proxy do not forward arbitrary libp2p TCP and QUIC traffic.

Change settings

Every relay option lives in /etc/minip2p-relay/relay.toml, so a change is an edit and a restart:

sudoedit /etc/minip2p-relay/relay.toml
sudo minip2p-relay service restart

Fields mirror the foreground flags. The file lists only what you changed; anything left out keeps the release’s default, and an unknown field stops the relay with an error:

hostname = "relay.example.com"          # announces /dns/relay.example.com on port 19876
key = "/var/lib/minip2p-relay/identity.key"
# quic = ["0.0.0.0:19876"]              # --quic; default: IPv4 and IPv6 on 19876
# announce = ["/dns/…"]                 # --announce, after the hostname's
# paused = true                         # --paused

[webtransport]                          # present = serve browsers
# cert = "/etc/minip2p-relay/tls/fullchain.pem"   # a CA-signed certificate
# key = "/etc/minip2p-relay/tls/privkey.pem"
# reload_secs = 30

[limits]                                # each --max-…/--…-rate flag, without dashes
max_reservations = 1024
max_circuit_bytes = 1048576
reservation_peer_rate = "3/250"         # CAPACITY/REFILL_MS or "off"

hostname announces /dns/<hostname>/tcp/19876 and /dns/<hostname>/udp/19876/quic-v1, plus /dns/<hostname>/udp/19876/quic-v1/webtransport with a CA certificate. It needs the default ports: with quic or tcp binds, list announce addresses instead.

To install a file you wrote, pass it instead of --hostname; it replaces the installed one. The service fills in its own key paths, and refuses a file naming other ones, so the identity stays at /var/lib/minip2p-relay/identity.key (use --import-key to bring one):

sudo minip2p-relay service install --config relay.toml

service install --hostname on a host that already has a config keeps it, and refuses if it names another hostname.

Check the service or follow its logs:

minip2p-relay service status
minip2p-relay service logs

Upgrades replace the installed binary. Restart the service to run it:

curl -fsSL https://minip2p.com/install/relay.sh | sh
sudo minip2p-relay service restart

sudo minip2p-relay service uninstall removes the unit but preserves the config, the identity, and a relay mesh’s backbone key.

Serve browsers

Add a [webtransport] section to the config (or --webtransport to the foreground command) to serve browsers on the QUIC port. The relay serves self-signed certificates derived from its key, rotating each 13-day Certificate period, and logs the address a browser dials, Certhash included:

[relay] webtransport=/ip4/…/udp/19876/quic-v1/webtransport/certhash/u…/p2p/12D3KooW…

The address survives restarts with the same key, but goes stale within about 26 days, so browsers must keep getting the current one from the logs. For one permanent /dns/relay.example.com/…/webtransport address, give the relay a CA-signed certificate: see Stable browser addresses.

Serve one address from several regions

Several relay servers can serve one relay address as a relay mesh. Geo DNS sends each client to the nearest node. Every node runs with the same identity, so the peer ID in the address is valid on any of them. When a client asks a node for a circuit to a peer reserved on another node, the first node forwards the circuit to the second over a QUIC backbone. Clients need no changes.

Each node also has a backbone key of its own for the backbone connections. The shared identity signs each node’s backbone key, so a node accepts any backbone peer whose key the identity signed, and no node keeps a list of the others to check against. Turn the mesh on with a [mesh] section. The first node lists no members:

hostname = "relay.example.com"

[mesh]
# listen = ["0.0.0.0:19877"]   # default: IPv4 and IPv6 on 19877
members = []                   # existing nodes' backbone addresses

service install creates the backbone key at /var/lib/minip2p-relay/mesh.key and prints the node’s member entry before starting the relay:

sudo minip2p-relay service install --config relay.toml
mesh_member_candidate=/ip4/0.0.0.0/udp/19877/quic-v1/p2p/12D3KooW...
mesh_member_candidate=/ip6/::/udp/19877/quic-v1/p2p/12D3KooW...

Replace the wildcard IP with the node’s public IP to get its member entry, and check it against the [relay] mesh listening= line in minip2p-relay service logs, which shows what actually bound.

Each later node lists every existing node’s entry, then installs once with the shared identity from /var/lib/minip2p-relay/identity.key on the first node:

[mesh]
members = [
  "/ip4/198.51.100.7/udp/19877/quic-v1/p2p/12D3KooW...",
  "/ip4/203.0.113.10/udp/19877/quic-v1/p2p/12D3KooW...",
]
sudo minip2p-relay service install --config relay.toml --import-key ./identity.key

A node dials the members it lists and accepts any member that dials it, so a link forms when either side lists the other. The existing nodes need no config change or restart, only a firewall rule for the new node’s IP. A node skips its own entry, and only the side that lists the other redials a dropped link. A backbone peer under another identity is refused with [relay] mesh peer=12D3KooW... rejected: member proof does not verify. To remove a node, stop it.

Allow UDP port 19877 only from the other nodes’ IP addresses. Keep the nodes’ clocks synced with NTP. Each node logs [relay] mesh member=12D3KooW... up when that member’s link is verified and down when the member leaves, and [relay] mesh member=12D3KooW... synced entries=3 once it has that member’s full directory: the number of reservations the member holds. Circuits forwarded across the backbone show the other node’s backbone peer ID as via= in their circuit opened and circuit closed lines.

Each node applies its own reservation, circuit, and rate limits. Mesh-wide limits are not supported. Every node holds the shared identity key, so a breach of any node exposes it, and replacing the key changes every published address.

In the foreground, --mesh-key PATH enables the mesh, --mesh-listen HOST:PORT replaces the default backbone listeners, and --mesh-member adds one member. Repeat --mesh-listen and --mesh-member as needed. A foreground --config with [mesh] needs key = "PATH" in that section, so the backbone key persists.

Run it in the foreground

For a terminal session instead of systemd:

mkdir -m 0700 -p "$HOME/.local/share/minip2p-relay"
minip2p-relay \
  --key "$HOME/.local/share/minip2p-relay/identity.key" \
  --announce /dns/relay.example.com/tcp/19876 \
  --announce /dns/relay.example.com/udp/19876/quic-v1

The process prints its peer ID and concrete listener addresses at startup. A client dials the announced address with the peer ID appended:

/dns/relay.example.com/tcp/19876/p2p/12D3KooW...
/dns/relay.example.com/udp/19876/quic-v1/p2p/12D3KooW...

The key file fixes the peer ID across restarts. The relay creates it with mode 0600 on Unix and refuses files owned by another user or files with broader permissions.

Run it with Docker

The container image supports Linux x86-64 and ARM64. A named volume keeps the relay identity across container replacements:

docker run -d \
  --name minip2p-relay \
  --restart unless-stopped \
  -p 19876:19876/tcp -p 19876:19876/udp \
  -v minip2p-relay-data:/data \
  ghcr.io/deepso7/minip2p-relay:latest

The image stores its identity in /data/identity.key by default. Pass relay options such as --announce after the image name.

The image runs as UID and GID 10001; make a bind-mounted data directory writable by that account. Publish both TCP and UDP ports because the relay serves TCP and QUIC on the same port. Host IPv6 publication follows the Docker daemon’s IPv6 configuration.

Use custom listener addresses

Repeat --tcp or --quic to replace the automatic listeners. This example uses separate ports and explicit IPv4 and IPv6 addresses:

minip2p-relay \
  --key /var/lib/minip2p-relay/identity.key \
  --tcp 192.0.2.10:4101 \
  --tcp '[2001:db8::10]:4101' \
  --quic 192.0.2.10:4201 \
  --quic '[2001:db8::10]:4201'

Run minip2p-relay --help for reservation, circuit, timeout, byte, and rate-limit options.

Last updated on

Was this page helpful?