Relays

birdd uses Nostr-compatible WebSocket relays to exchange signed events. A relay transports events.

Configure one or more relay URLs at the top level of birdd.toml:

relays = [
  "wss://relay-one.example",
  "wss://relay-two.example",
]

An empty list is valid and keeps the node local-only. Use multiple independent relays when federation availability matters.

Synchronizing

Run one synchronization pass with:

birdd --config birdd.toml sync

sync publishes retained local events, fetches remote history, applies valid new events, and prints the number of newly received transport events. Duplicate publication and reception are safe because Nostr event IDs are deterministic.

The long-running node repeats this process every five seconds by default:

birdd --config birdd.toml run --interval-seconds 5

If a sync fails, run logs the error and retries. Local commands and SQLite writes remain available while relays are down.

Failure behavior

At least one configured relay must be reachable for a sync to succeed. Fetch failures from one relay do not prevent other connected relays from being used. Outgoing events are attempted against every connected relay.

Restricted deliveries are considered published only after every configured relay has accepted the recipient’s encrypted event. A relay that stays offline can therefore leave restricted deliveries in the wrapped state even when another relay has accepted them.

Inspect relay and stream state with:

birdd --config birdd.toml federation-status
birdd --config birdd.toml federation-status --json

Note

Relays can replay, censor, duplicate, or lose events. Signatures prevent a relay from forging your flock, but relay history is not a backup.