Configuration reference

Basics

The configuration is a TOML file, by default named nostrfy.toml. Create it with init:

nostrfy --config nostrfy.toml init

Validate it (recommended before every start):

nostrfy --config nostrfy.toml check

Every command takes --config <path> (default nostrfy.toml).

General syntax:

[section]
key = "string"
key = 8080
key = [1, 2]
key = true

Configuration sections

Every key is optional; a missing key uses its default.

Section [relay] — relay identity

Key details

• private_key — the relay's own secret key, used to sign relay-generated events: NIP-29 group metadata (39000-39005) and NIP-43 role/membership events. Generate with nostrfy genkey; keep it secret. It is read once at startup, so changing it requires a restart; that restart also heals the stored group metadata — the previous key's relay-signed events are removed and the current state is republished under the new key (the group state itself is restored as-is, not rebuilt). The NIP-43 role state (membership, roles and invite codes) is healed the same way.
• livekit_participants_interval_secs — how often (seconds) the relay refreshes the NIP-29 kind:39004 participant lists by calling the LiveKit Room Service API (ListParticipants) with the configured credentials. LiveKit webhooks sent to /.well-known/nip29/livekit/webhook refresh a group's list immediately; the poll reconciles missed events. Must be at least 1. Fixed at startup — requires a restart.
• public_url — used to validate URL-bearing tags from clients: NIP-42 AUTH, NIP-62 vanish and NIP-98 admin auth. When empty, the relay falls back to host:port, which never matches a real client URL when binding 0.0.0.0 or 127.0.0.1 (a warning is logged). Always set it.
• enabled_nips vs disabled_nips — the allowlist wins: when enabled_nips is non-empty, only its NIPs are advertised and disabled_nips is ignored. Both require a restart.
• reject_ephemeral — kinds 20000-29999 are rejected, but the exempt kinds NIPs require to be relayed are still forwarded: 22242, 27235, 28934/28935/28936, 24133, 23194/23195, 24242 and 21059. Applies on SIGHUP.
• enabled_git — opt-in NIP-34: accepts kinds 1617-1633 and 30617/30618 and advertises NIP-34. Off by default because patch payloads can be large. Applies on SIGHUP.

Section [server] — server settings

Key details

• host — 0.0.0.0 binds all IPv4 interfaces; 127.0.0.1 is local only.
• port — 1-65535; port 80 requires root. This one port serves the WebSocket relay, the NIP-11 document, the REST API and the NIP-86 RPC together.
• api_host — dedicates the REST API to a single hostname so the API and the relay can share one port behind a reverse proxy. Fixed at startup — requires a restart.
• ws_paths — root serves / only, inbox-outbox serves /inbox and /outbox only, all serves both. Fixed at startup — requires a restart.
• trusted_proxies — list only the proxy's own addresses (loopback for nginx/Caddy on the same host, the balancer's source range in the cloud). With it set, the client IP is derived from the last untrusted X-Forwarded-For entry for the per-IP caps, rate limit, blockip and the logs. Never add an address clients can reach directly — they could spoof the header and bypass the per-IP limits. Fixed at startup — requires a restart.
• landing_page_file — by default a plain browser GET of the relay URL is answered with a built-in decoy page that reveals nothing about the relay. Point this at an HTML file to serve your own page instead (relay rules, contact, statistics); the NIP-11 document and WebSocket connections are unaffected. The file is read on demand and re-read when it changes, so an external job can regenerate it without a restart. It must be a regular file of at most 8 MiB (symlinks are not followed); when it is missing, the decoy page is served. Applies on SIGHUP.
• assets_dir — a directory whose files are served under /assets/<name> (images, CSS, JS for the landing page). Only flat ASCII names of letters, digits, ., _ and - are served (no dot-files, subdirectories or symlinks); unknown extensions are sent as application/octet-stream. Files are read per request, so they can be replaced in place. Fixed at startup — requires a restart.

Section [rpc] — NIP-86 management

The NIP-86 RPC is mounted on the relay's public POST / routes — there is no separate management port. management_token and admin_pubkey sometimes appear under [server] in old guides; those spellings are legacy aliases of these [rpc] keys.

Section [limits] — limits and protections

Connections and messages

Subscriptions and queries

Events

Legacy aliases: limits.require_pow, limits.new_pubkey_min_age_secs and limits.max_indexed_words are still accepted as aliases of relay.require_pow, relay.new_pubkey_min_age_secs and database.max_indexed_words.

REST API

Live fan-out

Section [database] — database

Key details

• map_size — the floor for the memory map: the map is always opened at least this large.
• max_map_size — the ceiling, opened as a sparse virtual reservation: physical disk grows only with the data actually written. Raise it when you hit database map is full.
• search_index = false — search still works (whole-word matching against content) but scans get slower; on a tiny VPS it halves the database. Recommended on small instances.
• disabled_fsync — trades durability for throughput: writes commit into the OS page cache and a power loss may lose the most recent writes.

Section [daemon] — daemon

Paths are resolved against the config file's directory, so they stay valid after the daemon changes its working directory.

/relay/stats needs no token and is readable cross-origin, so it serves a narrower view than the stats file: the host's free disk space and disk-full flag, the failure counters (db_errors, accept_errors, rebuild_failures, log_errors) and the per-reason connection-refusal breakdown are left out — together they would be a storage-capacity oracle for anonymous probers. They stay in the stats file (nostrfy stats prints them) and in /metrics. Note /metrics is unauthenticated too, so isolate it (api_host or the reverse proxy) if the capacity figures must stay private.

Section [access] — access control

The pubkey allow/deny lists are not config keys — they live in the relay database (LMDB) and are managed at runtime:

nostrfy relay allow npub1...
nostrfy relay deny npub1...
nostrfy relay list

• restrict_relay = true — only the allowlisted pubkeys may publish, while reading stays open to everyone (any client can still subscribe and fetch).
• A denied pubkey is always rejected when publishing and never served when reading.
• method_grants — NIP-86 method grants for non-admin pubkeys (pubkey → method names, e.g. a moderator allowed banevent and listbannedevents). Seeded from the config on the first run, then managed at runtime with NIP-86 assignmethod/unassignmethod (inspected with listmethodassignees). Only moderation and read methods are grantable — permission, role, invite-claim and relay-identity management stay admin-only, and a banned pubkey is refused even with grants. See the management API.

Section [blossom] — Blossom file server

Reloading at runtime (SIGHUP)

Editing the file and sending kill -HUP $(cat nostrfy.pid) reloads the config without a restart. Most settings take effect immediately; a few are fixed at startup:

[access] is not applied by a reload — the lists are seeded once at startup and then managed at runtime via NIP-86. The log warns when a restart-required setting changed, and a few startup-captured settings are not checked by the reload.