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