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.

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

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, installs the systemd unit, 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.

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 identity in /var/lib/minip2p-relay.

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.