Setting up a Relay for Magic Wormhole

magic-wormhole-relay.md

To set up a relay server for Magic Wormhole (a secure peer-to-peer file transfer tool), you need to deploy a transit relay component. This relay helps peers establish direct connections when they cannot communicate directly due to NAT/firewalls. Here's how to set it up:

---

1. Install the Transit Relay

Magic Wormhole’s transit relay is a separate Python-based server. Install it using pip:

# Install Python and pip (if not already installed)
sudo apt install python3 python3-pip  # Debian/Ubuntu

# Install the transit relay
pip3 install magic-wormhole-transit-relay

---

2. Run the Transit Relay

Start the relay server on your machine (e.g., using port 4001, the default port for Magic Wormhole):

wormhole-transit-relay --port=4001

This will start the relay listening on TCP port 4001. Use --port to customize the port.

---

3. Configure Firewall Rules

Allow traffic to the relay port (e.g., 4001). For ufw:

sudo ufw allow 4001/tcp

If behind NAT, forward the port on your router to the relay server’s local IP.

---

4. Use the Custom Relay in Magic Wormhole

Clients must specify your relay’s address when sending/receiving files. Add the --transit-helper flag:

# Example: Send a file using your custom relay
wormhole send --transit-helper=tcp:RELAY_IP:4001 myfile.txt

# Example: Receive a file
wormhole receive --transit-helper=tcp:RELAY_IP:4001

Replace RELAY_IP with your relay server’s public IP or domain.

---

5. (Optional) Secure with TLS

For encrypted communication between clients and your relay:

1. Generate TLS certificates (e.g., using Let’s Encrypt).
2. Run the relay with TLS:

wormhole-transit-relay --port=4001 --tls=cert.pem --tls-key=key.pem

Clients must use --transit-helper=tls:RELAY_IP:4001.

---

6. (Advanced) Use QUIC Instead of TCP

For lower latency, use QUIC (UDP-based) with wormhole-william, a Go-based Magic Wormhole client that supports QUIC relays.

Step 1: Deploy a QUIC Relay

# Download wormhole-william (includes a QUIC relay)
go install github.com/psanford/wormhole-william/cmd/wormhole@latest

# Run the QUIC relay
wormhole relay --quic --port 4242

Step 2: Use the QUIC Relay

wormhole-william send --relay-url quic://RELAY_IP:4242 myfile.txt

---

Key Notes

• The relay does not store files—it only helps peers establish direct connections.
• Magic Wormhole’s default public relay is tcp:magic-wormhole.io:4001. Override it with your own.
• For production, use TLS and run the relay as a service (e.g., with systemd).

---

Example systemd Service (for Auto-Start)

Create /etc/systemd/system/wormhole-relay.service:

[Unit]
Description=Magic Wormhole Transit Relay
After=network.target

[Service]
ExecStart=/usr/local/bin/wormhole-transit-relay --port=4001
Restart=always
User=wormhole
Group=wormhole

[Install]
WantedBy=multi-user.target

Start the service:

sudo systemctl enable --now wormhole-relay

---

Troubleshooting

• Check logs: journalctl -u wormhole-relay.
• Test connectivity: telnet RELAY_IP 4001.
• Ensure clients and relay use matching protocols (TCP/TLS/QUIC).

By hosting your own relay, you gain control over the infrastructure, improve privacy, and reduce reliance on public servers.