Run a Messenger Relay

A relay stores and forwards end-to-end encrypted messages for the swarm. It never sees plaintext. This guide covers running one on a real server and onboarding it into the registry.

Public tmor testnet (invited / controlled access): relays are foundation-operated and admitted by

the registry. Rewards are settled in dry-run until on-chain relay emission is activated (see the

roadmap).

Requirements

• A Linux server with Docker + Docker Compose.
• A domain / subdomain with TLS (Let's Encrypt recommended, so clients trust it natively).
• Open the relay's TLS port; do not expose any node RPC.

1. Encrypted at rest

Relays store messages in SQLCipher. Generate a strong per-relay key and keep it out of backups in the clear:

export MORANA_RELAY_DB_KEY=$(openssl rand -hex 32)

You can also point MORANA_RELAY_DB_KEY_FILE at a file containing the key instead.

The key's strength is on you. The relay refuses to open a persistent database with no key at

all — that much is enforced — but it does not check length or entropy. A one-character key is accepted.

Use openssl rand -hex 32 as above and do not improvise.

2. TLS

Use a real certificate for your domain (Let's Encrypt) so testers' apps trust it without shipping a private CA. Cleartext http:// to a non-loopback host is refused by clients.

3. Start the relay

Use the compose file from the deployment runbook (deploy/local-swarm/), adjusting the endpoint to your real https://relay-N.yourdomain address. Bring it up:

docker compose up -d --build

4. Onboard into the registry

Your relay self-registers with the registry, which then re-signs the relay list to include your real endpoint:

scripts/local_lan/onboard_swarm.sh    # or follow the swarm README

The registry's Root key stays offline — only the delegated epoch key signs the live list on the server. Clients pin the Root public key.

5. Verify

• morana-relay-registry-cli health --url <registry> --admin-token <token> — your relay appears in the list with its status and health score. This is foundation-admin tooling: it is built only with the closed-testnet-admin feature and is absent from a default build.
• The signed relay list now contains your real endpoint.
• The challenger's probes pass; an unhealthy relay is suspended and drops out of the list automatically.

Operating notes

• Do not log client IPs. Check your reverse-proxy and relay log config.
• Persistence, storage caps, and rate limits are built in — a single relay cannot be flooded into filling its disk.
• Keep the server patched, SSH key-only, and firewalled to just the TLS port + SSH.