Configuration

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.
• 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.

Section [rpc] — NIP-86 management

Section [limits] — limits and protections

Connections and messages

Subscriptions and queries

Events

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.

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 allow-listed 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.

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.