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

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

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

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

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

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