Relay

A relay is a public node that does two jobs for the network — and nothing else:

1. NAT traversal. Most devices sit behind NATs that drop unsolicited connections. A relay helps two peers punch a direct path, and forwards their (still encrypted) session if a direct path can’t be formed.
2. A dead-drop store. When a recipient is offline, the sender leaves an encrypted blob at a rotating address; the relay holds it until the recipient collects it.

What a relay can and cannot see

A relay is deliberately blind. It:

• Cannot read messages — everything is end-to-end encrypted; the relay sees only padded ciphertext.
• Cannot see who talks to whom — dead-drop addresses are derived from a shared secret, rotate hourly, and are unlinkable, so a relay can’t tie a sender to a recipient or link two messages as one conversation.
• Holds no accounts and no history — undelivered blobs expire automatically (default 7 days) and are deleted once acknowledged.

Relays are interchangeable: any relay works, clients route around one that’s blocked or gone, and you can point Wisp at any relay you choose in the app’s relay settings.

Abuse resistance

To stop a relay being used as free storage, each one enforces:

• a size cap on blobs (default 4096 bytes),
• a quota per drop address (default 16 blobs),
• and a TTL after which undelivered blobs are swept (default 7 days).

Run your own relay

The relay is a standalone Rust binary (wisp-relay) in the core/ workspace, and the repository ships a Docker setup under relay/.

git clone https://github.com/xmahdi1/Wisp.git
cd Wisp/relay
cp .env.example .env
# edit .env — set a stable WISP_RELAY_SEED and your public IP
docker compose up -d --build

Key settings (see relay/.env.example and relay/config.example.toml):

• WISP_RELAY_SEED — a seed phrase that fixes the relay’s identity (PeerId) across restarts. Keep it stable so clients don’t have to rediscover the relay.
• WISP_RELAY_PUBLIC_IP — the public address clients should dial.
• WISP_RELAY_PORT — the listen port (default 4001, TCP + QUIC).

Once it’s running, add its address in the app under relay settings, and it will also serve the DHT and the optional instant-wake protocol. Running a relay exposes no message content or social graph — see Security for why.