Install with Docker

Docker is the only officially documented relay installation method. No standalone relay binary is currently published.

Prerequisites

• Docker on a Linux amd64 host.
• A public IPv4 address or DNS name for the relay.
• An external port available and reachable over both TCP and UDP (41234 by default).
• Enough persistent disk space for the relay databases and state.

Start the relay

Pull the current image:

docker pull ghcr.io/mockingmagician/mesh-relay:latest

Create a named volume and start the container:

docker volume create mesh-relay-data

docker run -d \
  --name mesh-relay \
  --restart unless-stopped \
  -p 41234:41234/tcp \
  -p 41234:41234/udp \
  -v mesh-relay-data:/data \
  ghcr.io/mockingmagician/mesh-relay:latest \
  --host relay.example.org \
  --external-port 41234 \
  --origins 88.186.133.102:12000,88.186.133.102:12001

The two origins bootstrap the relay into the public Mesh network. --host and --external-port form the address advertised to other relays; they do not change the container bind address.

Use a different external port

The relay always listens on port 41234 inside the container. To publish it as relay.example.org:12000, map port 12000 to the internal port for both protocols and advertise the same value:

docker run -d \
  --name mesh-relay \
  --restart unless-stopped \
  -p 12000:41234/tcp \
  -p 12000:41234/udp \
  -v mesh-relay-data:/data \
  ghcr.io/mockingmagician/mesh-relay:latest \
  --host relay.example.org \
  --external-port 12000 \
  --origins 88.186.133.102:12000,88.186.133.102:12001

The Docker host port and --external-port must match. Allow that chosen port in the host firewall, provider firewall and any NAT rule.

Docker Compose

The equivalent Compose service is:

services:
  relay:
    image: ghcr.io/mockingmagician/mesh-relay:latest
    container_name: mesh-relay
    restart: unless-stopped
    ports:
      - "41234:41234/tcp"
      - "41234:41234/udp"
    volumes:
      - mesh-relay-data:/data
    command:
      - --host
      - relay.example.org
      - --external-port
      - "41234"
      - --origins
      - 88.186.133.102:12000,88.186.133.102:12001

volumes:
  mesh-relay-data:

Start it with docker compose up -d.

Verify the container

docker ps --filter name=mesh-relay
docker logs --tail 100 mesh-relay

Confirm that Docker publishes the chosen external port over TCP and UDP, then test reachability from outside the host network. A running container alone does not prove that NAT and firewall rules are correct.

Next steps

Read Configuration before changing arguments, then configure updates and backups.