Nostr-Email Bridge Deployment Guide

This document covers deploying the ORLY Nostr-Email bridge (Marmot DM to SMTP).

Architecture Overview

The bridge converts between Nostr Marmot DMs and standard email:

Inbound email (someone@internet → npub@yourdomain): SMTP server receives the email, parses MIME, zips non-text parts, encrypts with ChaCha20-Poly1305, uploads to Blossom, and delivers as a Marmot DM with a fragment-key URL.
Outbound email (npub sends DM with To: headers): Bridge parses the DM, checks subscription + rate limits, and sends via SMTP with DKIM signing.

Deployment Modes

Mode	Description	Config
Monolithic	Bridge runs inside the ORLY relay process	`ORLY_BRIDGE_ENABLED=true`
Standalone	Bridge runs as a separate process	`orly bridge` subcommand
Launcher	Bridge managed by the process supervisor	`ORLY_LAUNCHER_BRIDGE_ENABLED=true`

Monolithic is simplest for single-server deployments. Standalone is useful when the relay and bridge run on different hosts.

Quick Start (Monolithic)

# 1. Generate DKIM keys
./scripts/generate-dkim.sh yourdomain.com

# 2. Set environment variables
export ORLY_BRIDGE_ENABLED=true
export ORLY_BRIDGE_DOMAIN=yourdomain.com
export ORLY_BRIDGE_SMTP_PORT=2525
export ORLY_BRIDGE_DKIM_KEY=/path/to/dkim-private.pem
export ORLY_BRIDGE_DKIM_SELECTOR=marmot
export ORLY_BRIDGE_COMPOSE_URL=https://yourdomain.com/compose

# 3. Start relay (bridge starts automatically)
./orly

The compose form is served at /compose and the decrypt page at /decrypt.

DNS Configuration

All DNS records are required for email deliverability. Without them, outbound email will be rejected by most providers.

MX Record

Points incoming email for your domain to your bridge server.

yourdomain.com.  IN  MX  10  mail.yourdomain.com.
mail.yourdomain.com.  IN  A  <YOUR_SERVER_IP>

If your relay is the same host:

yourdomain.com.  IN  MX  10  yourdomain.com.

SPF Record

Authorizes your server to send email for the domain.

yourdomain.com.  IN  TXT  "v=spf1 ip4:<YOUR_SERVER_IP> -all"

For multiple IPs:

yourdomain.com.  IN  TXT  "v=spf1 ip4:1.2.3.4 ip4:5.6.7.8 -all"

DKIM Record

The generate-dkim.sh script outputs the exact DNS record. The selector defaults to marmot.

marmot._domainkey.yourdomain.com.  IN  TXT  "v=DKIM1; k=rsa; p=MIIBIjANBg..."

The value is the base64-encoded RSA public key (no line breaks in the DNS TXT record).

DMARC Record

Tells receivers how to handle mail that fails SPF/DKIM.

_dmarc.yourdomain.com.  IN  TXT  "v=DMARC1; p=quarantine; rua=mailto:postmaster@yourdomain.com"

For testing, start with p=none (report only, don't reject):

_dmarc.yourdomain.com.  IN  TXT  "v=DMARC1; p=none; rua=mailto:postmaster@yourdomain.com"

Reverse DNS (PTR)

The PTR record maps your server's IP address back to your domain. Mail servers check that the IP sending mail resolves to the domain it claims to be.

<YOUR_IP>  IN  PTR  yourdomain.com.

Important ordering: The forward A record (yourdomain.com → <IP>) must exist and propagate before you set the PTR. Many providers verify the forward record when you create the reverse, and will reject or silently remove the PTR if the A record doesn't match.

How to set it: PTR records are set by the IP owner (your VPS provider), not the domain registrar. Look for "Reverse DNS", "rDNS", or "PTR" in your provider's control panel, usually under Networking or IP settings.

Provider	Where to find it
Hetzner	Cloud Console → Server → Networking → Primary IPs → Edit
DigitalOcean	Droplet → Networking → PTR Records
Vultr	Server → Settings → IPv4 → Reverse DNS
Linode/Akamai	Linode → Network → IP Addresses → Edit rDNS
Mynymbox	Management panel → Reverse DNS

Verify after setting:

dig -x YOUR_SERVER_IP +short
# Expected: yourdomain.com.

If the output still shows the provider's default hostname (e.g., static.50.235.71.80.virtservers.com), the PTR hasn't propagated or wasn't accepted. Check that your A record is correct and retry.

DKIM Key Generation

Use the provided script:

./scripts/generate-dkim.sh yourdomain.com [selector]

This generates:

dkim-private.pem — the private key (keep secret, set ORLY_BRIDGE_DKIM_KEY to this path)
Console output with the DNS TXT record to add

If you prefer manual generation:

openssl genrsa -out dkim-private.pem 2048
openssl rsa -in dkim-private.pem -pubout -outform DER | openssl base64 -A
# Use the base64 output as the "p=" value in the DNS TXT record

Port 25 Workarounds

Many cloud providers block port 25 by default. The bridge listens on port 2525 (configurable via ORLY_BRIDGE_SMTP_PORT). You need to get traffic from port 25 to your bridge port.

Method 1: iptables Redirect (Recommended)

Redirect port 25 to your bridge port. No binary changes needed.

sudo iptables -t nat -A PREROUTING -p tcp --dport 25 -j REDIRECT --to-port 2525

Make it persistent across reboots:

sudo apt install iptables-persistent
sudo netfilter-persistent save

Method 2: setcap (Bind Port 25 Directly)

Grant the binary permission to bind low ports without root:

sudo setcap 'cap_net_bind_service=+ep' ./orly

Then set ORLY_BRIDGE_SMTP_PORT=25.

Note: setcap is cleared if you replace the binary, so re-run after each deploy.

Method 3: systemd Socket Activation

systemd listens on port 25 and passes the file descriptor to the bridge.

# /etc/systemd/system/orly-smtp.socket
[Socket]
ListenStream=25
Accept=no

[Install]
WantedBy=sockets.target

Then configure the bridge to accept the systemd socket. This requires custom code not yet in the bridge — use iptables for now.

Method 4: Provider Unblock Request

Some providers will open port 25 on request:

Provider	Process
DigitalOcean	Support ticket, explain mail server use case
Vultr	Support ticket
Linode/Akamai	Support ticket (usually approved for new accounts after a period)
AWS EC2	Request via SES, or use an Elastic IP with port 25 unblock form

Method 5: Providers with Port 25 Open

These providers do not block port 25 by default:

Hetzner (cloud and dedicated)
OVH
Most dedicated server providers (Leaseweb, ServerCheap, etc.)
Self-hosted / home server (if your ISP allows it)

Method 6: SSH Tunnel

If you have a separate server with port 25 open:

# On the port-25-capable server:
ssh -R 2525:localhost:2525 user@bridge-host

Or use autossh for persistent tunnels:

autossh -M 0 -N -R 25:localhost:2525 user@bridge-host

Method 7: WireGuard / VPN Tunnel

Run a VPN between a port-25-capable server and your bridge host:

# On the port-25 server, forward port 25 to the bridge via WireGuard peer IP
iptables -t nat -A PREROUTING -p tcp --dport 25 -j DNAT --to-destination 10.0.0.2:2525
iptables -t nat -A POSTROUTING -j MASQUERADE

Method 8: Docker with Host Networking

docker run --network host -e ORLY_BRIDGE_SMTP_PORT=2525 ...
# Then use iptables method above on the host

Method 9: Separate Mail Server (Postfix Relay)

Run Postfix on a port-25-capable host and pipe to the bridge via LMTP or HTTP webhook:

# /etc/postfix/main.cf
transport_maps = hash:/etc/postfix/transport

# /etc/postfix/transport
yourdomain.com  lmtp:bridge-host:2525

This is the most complex option but works well if you already run a mail server.

Environment Variables

All bridge configuration is via environment variables with the ORLY_BRIDGE_ prefix.

Variable	Default	Description
`ORLY_BRIDGE_ENABLED`	`false`	Enable the email bridge
`ORLY_BRIDGE_DOMAIN`		Email domain (e.g., `relay.example.com`)
`ORLY_BRIDGE_NSEC`		Bridge identity nsec (default: relay identity from database)
`ORLY_BRIDGE_RELAY_URL`		The relay that the bridge will connect to - use the public URL even if running in monolithic (single binary, no gRPC bridging) mode. Also allows remote relays to be used in the same way as the bridge is a standalone unit.
`ORLY_BRIDGE_SMTP_PORT`	`2525`	SMTP server listen port
`ORLY_BRIDGE_SMTP_HOST`	`0.0.0.0`	SMTP server listen address
`ORLY_BRIDGE_DATA_DIR`	`$ORLY_DATA_DIR/bridge`	Bridge data directory
`ORLY_BRIDGE_DKIM_KEY`		Path to DKIM private key PEM file
`ORLY_BRIDGE_DKIM_SELECTOR`	`marmot`	DKIM selector for DNS TXT record
`ORLY_BRIDGE_NWC_URI`		NWC connection string for subscription payments (falls back to `ORLY_NWC_URI`)
`ORLY_BRIDGE_MONTHLY_PRICE_SATS`	`2100`	Monthly subscription price in sats
`ORLY_BRIDGE_ALIAS_PRICE_SATS`	`4200`	Monthly alias email price in sats
`ORLY_BRIDGE_COMPOSE_URL`		Public URL of the compose form
`ORLY_BRIDGE_SMTP_RELAY_HOST`		SMTP smarthost for outbound delivery (e.g., `smtp.migadu.com`)
`ORLY_BRIDGE_SMTP_RELAY_PORT`	`587`	SMTP smarthost port (587 for STARTTLS)
`ORLY_BRIDGE_SMTP_RELAY_USERNAME`		SMTP smarthost AUTH username
`ORLY_BRIDGE_SMTP_RELAY_PASSWORD`		SMTP smarthost AUTH password
`ORLY_BRIDGE_ACL_GRPC_SERVER`		gRPC address of ACL server (split IPC mode with paid ACL)
`ORLY_BRIDGE_PROFILE`	`$DATA_DIR/profile.txt`	Path to profile template file (kind 0 metadata)

NWC Wallet Setup

The bridge uses Nostr Wallet Connect (NWC) to create Lightning invoices for subscription payments. You need a Lightning wallet that supports NWC and can generate a connection string.

Getting an NWC Connection String

Option A: Alby (hosted, simplest)

Go to getalby.com and create an account (or log in)
Go to Settings → Wallet Connections (or visit getalby.com/apps)
Click "Create a new connection"
Name it (e.g., "Marmot Bridge")
Under permissions, enable only: make_invoice and lookup_invoice
Do not enable pay_invoice or any spending permissions
Copy the connection string — it looks like: nostr+walletconnect://pubkey?relay=wss://...&secret=...

Option B: Self-hosted (Alby Hub, LNbits, NWC-enabled node)

Most self-hosted Lightning wallets with NWC support have an "Apps" or "Connections" section where you can create restricted connection strings. The process is similar — create a new app connection with only make_invoice and lookup_invoice permissions.

Set the Environment Variable

export ORLY_BRIDGE_NWC_URI="nostr+walletconnect://pubkey?relay=wss://relay.getalby.com/v1&secret=hexsecret"

Or use ORLY_NWC_URI if the bridge shares the wallet with the relay.

The bridge only needs to create invoices and check payment status. It never needs pay_invoice or any spending capability. If your wallet forces you to grant all permissions, create a separate wallet for the bridge.

Subscription Model

Users send the word subscribe as a DM to the bridge identity. The bridge:

Creates a Lightning invoice via NWC
Sends the invoice back as a DM
Polls for payment (configurable interval)
On payment: activates a 30-day subscription, confirms via DM

Subscription state is stored in $ORLY_BRIDGE_DATA_DIR/subscriptions.json.

Rate limits for subscribed users:

10 outbound emails per hour per user
50 outbound emails per day per user
100 outbound emails per hour globally
500 outbound emails per day globally
30 second minimum interval between sends

Bridge Profile (Kind 0)

The bridge can publish a kind 0 (profile metadata) event on startup so Nostr clients can discover it and display a name, avatar, and description. Without a profile, clients show the bridge as an unknown pubkey.

Create a profile.txt in the bridge data directory using email-header format:

name: Marmot Bridge
about: Nostr-Email bridge at yourdomain.com. DM 'subscribe' to get started.
picture: https://yourdomain.com/avatar.png
nip05: bridge@yourdomain.com
lud16: tips@yourdomain.com
website: https://yourdomain.com
banner: https://yourdomain.com/banner.png

The bridge reads this file on every startup and publishes a kind 0 event signed with its identity. Lines with empty values are omitted. Comments (lines starting with #) are ignored.

To use a custom path instead of $ORLY_BRIDGE_DATA_DIR/profile.txt:

export ORLY_BRIDGE_PROFILE=/etc/orly/bridge-profile.txt

A template is provided at profile.example.txt in the repository root.

Blossom Server Configuration

The bridge uses Blossom for attachment storage. Ensure Blossom is enabled:

ORLY_BLOSSOM_ENABLED=true

When an inbound email has non-plaintext attachments, the bridge:

Bundles them into a flat ZIP
Encrypts with ChaCha20-Poly1305 (random key)
Uploads to Blossom as an opaque blob
Includes the URL with #key fragment in the DM

The encryption key is in the URL fragment, which per RFC 3986 is never sent to the server. Only the DM recipient (who has the full URL) can decrypt.

Compose Form

The compose form at /compose is a static HTML page with no server-side logic. It:

Reads pre-populated fields from the URL fragment: #to=alice@example.com&subject=Re: Hello
Formats the DM with RFC 822-style headers
Copies the formatted text to the clipboard
The user pastes this into a Nostr client as a DM to the bridge

The decrypt page at /decrypt allows email recipients to decrypt attachment URLs:

Enter the Blossom URL with #key fragment
The page downloads the blob, decrypts locally in the browser using ChaCha20-Poly1305
The decrypted file is offered for download
The key never leaves the browser

Pre-Flight Checklist

Run this before requesting port 25 from your provider, or before going live. Every check must pass.

# Replace with your actual domain and IP
DOMAIN=yourdomain.com
IP=1.2.3.4

echo "=== MX ==="
dig MX $DOMAIN +short
# Expected: 10 yourdomain.com.  (or your MX host)

echo "=== SPF ==="
dig TXT $DOMAIN +short | grep spf
# Expected: "v=spf1 ip4:$IP -all"

echo "=== DKIM ==="
dig TXT marmot._domainkey.$DOMAIN +short
# Expected: "v=DKIM1; k=rsa; p=MIIBIj..."

echo "=== DMARC ==="
dig TXT _dmarc.$DOMAIN +short
# Expected: "v=DMARC1; p=none; ..." or "p=quarantine"

echo "=== PTR ==="
dig -x $IP +short
# Expected: yourdomain.com.  (MUST match your domain, not the provider default)

echo "=== A record (forward) ==="
dig A $DOMAIN +short
# Expected: $IP

If PTR still shows the provider's default hostname, see the Reverse DNS section above. Many providers require the forward A record to exist before they accept the PTR.

Also check MX Toolbox email health for your domain — it flags common issues that will cause mail rejection.

Troubleshooting

Verify DNS Records

# Check MX record
dig MX yourdomain.com +short

# Check SPF
dig TXT yourdomain.com +short

# Check DKIM
dig TXT marmot._domainkey.yourdomain.com +short

# Check DMARC
dig TXT _dmarc.yourdomain.com +short

# Check PTR (reverse DNS)
dig -x YOUR_SERVER_IP +short

Online Tools

MX Toolbox — comprehensive DNS and mail server testing
mail-tester.com — send a test email, get a deliverability score
DKIM Validator — verify DKIM signing works

Common Issues

Outbound email rejected as spam:

Check SPF, DKIM, and DMARC records are all set correctly
Verify PTR record matches your sending domain
Check IP reputation at multirbl.valli.org
New IPs may need "warming up" — start with low volume

SMTP connection refused on port 25:

Your provider likely blocks port 25; see Port 25 Workarounds above
Verify with: telnet yourdomain.com 25

Bridge identity mismatch:

In monolithic mode, the bridge uses the relay's identity from the database
Set ORLY_BRIDGE_NSEC explicitly to override
Check the log for "bridge identity:" at startup

Subscription payments not working:

Verify NWC URI is correct and the wallet is online
The NWC URI must support make_invoice and lookup_invoice
Check the bridge data directory for subscriptions.json

Attachments not working:

Ensure ORLY_BLOSSOM_ENABLED=true
The Blossom server must be reachable from the compose/decrypt pages
Check that the domain serves Blossom at /blossom/ or root

Example: Full Production Setup

# DNS records (set via your registrar):
# yourdomain.com  MX 10  yourdomain.com
# yourdomain.com  TXT    "v=spf1 ip4:1.2.3.4 -all"
# marmot._domainkey.yourdomain.com  TXT  "v=DKIM1; k=rsa; p=..."
# _dmarc.yourdomain.com  TXT  "v=DMARC1; p=quarantine; rua=mailto:postmaster@yourdomain.com"

# Generate DKIM key
./scripts/generate-dkim.sh yourdomain.com marmot

# Environment
export ORLY_PORT=3334
export ORLY_BRIDGE_ENABLED=true
export ORLY_BRIDGE_DOMAIN=yourdomain.com
export ORLY_BRIDGE_SMTP_PORT=2525
export ORLY_BRIDGE_DKIM_KEY=/etc/orly/dkim-private.pem
export ORLY_BRIDGE_DKIM_SELECTOR=marmot
export ORLY_BRIDGE_COMPOSE_URL=https://yourdomain.com/compose
export ORLY_BRIDGE_NWC_URI="nostr+walletconnect://..."
export ORLY_BRIDGE_MONTHLY_PRICE_SATS=2100
export ORLY_BLOSSOM_ENABLED=true

# Redirect port 25 to bridge SMTP port
sudo iptables -t nat -A PREROUTING -p tcp --dport 25 -j REDIRECT --to-port 2525
sudo netfilter-persistent save

# Start
./orly

SMTP Smarthost (Migadu, Mailgun, etc.)

Instead of direct MX delivery with self-managed DKIM/SPF, you can relay outbound email through a hosted email provider. This simplifies DNS setup and improves deliverability since the provider handles IP reputation.

When ORLY_BRIDGE_SMTP_RELAY_HOST is set, the bridge sends all outbound mail through the smarthost using STARTTLS + PLAIN authentication instead of direct MX delivery.

export ORLY_BRIDGE_SMTP_RELAY_HOST=smtp.migadu.com
export ORLY_BRIDGE_SMTP_RELAY_PORT=587
export ORLY_BRIDGE_SMTP_RELAY_USERNAME=bridge@yourdomain.com
export ORLY_BRIDGE_SMTP_RELAY_PASSWORD=your-app-password

The bridge's own DKIM signing (ORLY_BRIDGE_DKIM_KEY) is bypassed when using a smarthost since the provider signs outbound mail with their own DKIM keys.

Example: Migadu Deployment (relay.orly.dev)

This is a worked example of deploying the bridge on a Linode VPS using Migadu as the hosted email provider for the subdomain relay.orly.dev. The domain registrar is Namecheap.

1. Add Domain in Migadu

Log into admin.migadu.com, go to Domains, add relay.orly.dev.

Migadu will show a list of required DNS records and a verification TXT value unique to your account.

2. DNS Records (Namecheap)

In Namecheap's Advanced DNS panel for orly.dev, add the following records. Since relay.orly.dev is a subdomain, the Host field is relay (not @).

MX Records

Type	Host	Value	Priority	TTL
MX	relay	aspmx1.migadu.com	10	1 min
MX	relay	aspmx2.migadu.com	20	1 min

TXT Records

Type	Host	Value	TTL
TXT	relay	v=spf1 include:spf.migadu.com -all	1 min
TXT	relay	hosted-email-verify=XXXXXXXX	1 min
TXT	_dmarc.relay	v=DMARC1; p=quarantine;	1 min

Replace XXXXXXXX with the verification value from Migadu's admin panel.

CNAME Records (DKIM)

Type	Host	Value	TTL
CNAME	key1._domainkey.relay	key1.relay.orly.dev._domainkey.migadu.com	1 min
CNAME	key2._domainkey.relay	key2.relay.orly.dev._domainkey.migadu.com	1 min
CNAME	key3._domainkey.relay	key3.relay.orly.dev._domainkey.migadu.com	1 min

The A record for relay.orly.dev pointing to the VPS (e.g., 69.164.249.71) remains unchanged. MX and A records coexist without conflict.

3. Verify in Migadu

After adding DNS records (propagation is typically under 5 minutes with 1-minute TTL), go back to Migadu's domain page and run the DNS check. All checks should pass.

Verify locally:

dig relay.orly.dev MX +short
# Expected: 10 aspmx1.migadu.com.  20 aspmx2.migadu.com.

dig relay.orly.dev TXT +short
# Expected: "v=spf1 include:spf.migadu.com -all"  "hosted-email-verify=..."

dig _dmarc.relay.orly.dev TXT +short
# Expected: "v=DMARC1; p=quarantine;"

dig key1._domainkey.relay.orly.dev CNAME +short
# Expected: key1.relay.orly.dev._domainkey.migadu.com.

4. Create Mailbox in Migadu

In Migadu admin, create a mailbox for the bridge (e.g., bridge@relay.orly.dev). Note the password — this is used for SMTP authentication.

5. Inbound Email Forwarding

Migadu receives inbound email for relay.orly.dev via its MX servers. To deliver it to the bridge's SMTP server on the VPS, set up forwarding:

Option A: Migadu forwards to a subdomain with direct MX

Create a subdomain bridge.relay.orly.dev with MX pointing directly at the VPS:

Type	Host	Value	Priority
MX	bridge.relay	relay.orly.dev	10

In Migadu, set up a catch-all forwarding rule to forward *@relay.orly.dev to incoming@bridge.relay.orly.dev.

On the VPS, open port 25 and redirect to the bridge's SMTP port:

sudo iptables -t nat -A PREROUTING -p tcp --dport 25 -j REDIRECT --to-port 2525
sudo netfilter-persistent save

Option B: Migadu sieve forwarding to VPS

In Migadu's mailbox settings, add a sieve filter or forwarding rule that re-sends incoming mail to an address handled by the bridge's SMTP server.

6. Bridge Environment

Add to the ORLY service environment (.env file or systemd unit):

ORLY_BRIDGE_ENABLED=true
ORLY_BRIDGE_DOMAIN=relay.orly.dev
ORLY_BRIDGE_SMTP_PORT=2525
ORLY_BRIDGE_SMTP_HOST=0.0.0.0
ORLY_BRIDGE_SMTP_RELAY_HOST=smtp.migadu.com
ORLY_BRIDGE_SMTP_RELAY_PORT=587
ORLY_BRIDGE_SMTP_RELAY_USERNAME=bridge@relay.orly.dev
ORLY_BRIDGE_SMTP_RELAY_PASSWORD=<migadu-password>
ORLY_BRIDGE_NWC_URI=nostr+walletconnect://...
ORLY_BRIDGE_MONTHLY_PRICE_SATS=2100
ORLY_BRIDGE_COMPOSE_URL=https://relay.orly.dev/compose

7. Build and Deploy

# Build unified binary with web UI
./scripts/update-embedded-web.sh
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o orly ./cmd/orly

# Deploy
ssh root@relay.orly.dev 'systemctl stop orly'
rsync -avz --compress -e "ssh -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes" \
  orly root@relay.orly.dev:/home/mleku/.local/bin/
ssh root@relay.orly.dev 'chown mleku:mleku /home/mleku/.local/bin/orly && systemctl start orly'

8. Verify

# Check bridge started
ssh root@relay.orly.dev 'journalctl -u orly --since "1 min ago" | grep bridge'
# Expected: "bridge identity: npub1..." and "bridge started"

# Test outbound: DM the bridge npub with "subscribe"
# Test inbound: send email to npub1...@relay.orly.dev

Client Setup: White Noise

White Noise is a mobile/desktop Nostr messaging client that uses NIP-17 gift-wrapped DMs. When searching for the bridge by its npub, White Noise may show the profile but say the bridge "isn't on White Noise yet." This means White Noise cannot find the bridge's relay list and doesn't know where to send messages.

Why This Happens

White Noise (and other NIP-17 clients) discover where to send DMs by looking up the recipient's kind 10002 event (NIP-65 relay list metadata). This event tells clients which relays a user reads from and writes to. Without it, the client has no delivery target for gift-wrapped DMs.

The bridge currently publishes a kind 0 (profile) on startup but does not publish a kind 10002 relay list. Until the bridge publishes one automatically, you need to publish it manually.

Publishing a Relay List for the Bridge

Use any Nostr tool that can publish events with an arbitrary key. The event must be signed by the bridge's identity key (the nsec used for ORLY_BRIDGE_NSEC, or the relay's auto-generated identity if no explicit nsec is set).

The kind 10002 event looks like:

{
  "kind": 10002,
  "content": "",
  "tags": [
    ["r", "wss://relay.orly.dev/"],
    ["r", "wss://relay.damus.io/", "read"],
    ["r", "wss://nos.lol/", "read"]
  ]
}

Each r tag is a relay URL. Tags without a marker (no third element) mean both read and write. "read" means the bridge reads from that relay but doesn't write there. "write" means write-only.

At minimum, include the bridge's own relay as a read+write relay:

["r", "wss://your-relay-domain/"]

Adding popular public relays as read entries helps clients that don't connect to your relay directly find the bridge.

Step-by-Step with nak

nak is a command-line Nostr tool. Install it, then publish the relay list:

# Set the bridge's secret key
export NOSTR_SECRET_KEY=nsec1...  # The bridge identity nsec

# Publish kind 10002 with your relay as read+write, plus popular relays as read-only
nak event \
  --kind 10002 \
  --tag r='wss://relay.orly.dev/' \
  --tag r='wss://relay.damus.io/;read' \
  --tag r='wss://nos.lol/;read' \
  wss://relay.orly.dev wss://relay.damus.io wss://nos.lol

Publish to multiple relays so clients can discover it regardless of which relays they check.

Step-by-Step with nostril

nostril is another CLI option:

nostril --kind 10002 \
  --sec <bridge-hex-secret> \
  --tag r 'wss://relay.orly.dev/' \
  --tag r 'wss://relay.damus.io/' read \
  --tag r 'wss://nos.lol/' read \
  | websocat wss://relay.orly.dev

Verifying the Relay List

After publishing, verify that clients can find it:

# With nak
nak req -k 10002 -a <bridge-pubkey-hex> wss://relay.orly.dev

# Or check on a web viewer
# https://njump.me/<bridge-npub>

White Noise should now show the bridge as reachable. Search for the bridge npub again and the "isn't on White Noise yet" message should be replaced with the ability to start a conversation.

Recommended Relay List

For maximum discoverability, include the bridge's own relay plus 2-3 popular relays:

Relay	Marker	Purpose
`wss://your-relay.com/`	(none)	Primary — bridge reads and writes here
`wss://relay.damus.io/`	read	Popular relay, helps discovery
`wss://nos.lol/`	read	Popular relay, helps discovery
`wss://relay.nostr.band/`	read	Indexer relay, helps discovery

Future: Automatic Relay List Publishing

A future ORLY release will have the bridge publish kind 10002 automatically on startup alongside the kind 0 profile, eliminating this manual step.

BRIDGE_DEPLOYMENT.md raw