---
title: Host a relay server
description: 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](/docs/reference/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`:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```toml
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):

```bash
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:

```bash
minip2p-relay service status
minip2p-relay service logs
```

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

```bash
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:

```text
[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](/docs/rust/webtransport-certificates).

### 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:

```toml
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:

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

```text
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:

```toml
[mesh]
members = [
  "/ip4/198.51.100.7/udp/19877/quic-v1/p2p/12D3KooW...",
  "/ip4/203.0.113.10/udp/19877/quic-v1/p2p/12D3KooW...",
]
```

```bash
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:

```bash
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:

```text
/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:

```bash
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:

```bash
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.
