CONFIGURATION.md

Configuration

Environment variables

The following environment variables can be set:

Name	Description	Default
SECRET	Long random secret.	changeme
RELAY_PORT	Relay's server port	8008
RELAY_PRIVATE_KEY	Relay's private key in hex	(auto-generated)
WORKER_COUNT	Number of workers override	No. of available CPUs
DB_URI	PostgreSQL URI (overrides DB_HOST, DB_PORT, etc.)
DB_HOST	PostgresSQL Hostname
DB_PORT	PostgreSQL Port	5432
DB_USER	PostgreSQL Username	nostr_ts_relay
DB_PASSWORD	PostgreSQL Password	nostr_ts_relay
DB_NAME	PostgreSQL Database name	nostr_ts_relay
DB_MIN_POOL_SIZE	Min. connections per worker	0
DB_MAX_POOL_SIZE	Max. connections per worker	3
DB_ACQUIRE_CONNECTION_TIMEOUT	New connection timeout (ms)	60000
READ_REPLICA_ENABLED	Read Replica (RR) Toggle	'false'
READ_REPLICAS	Number of read replicas (RR0, RR1, ..., RRn)	2
RR0_DB_HOST	PostgresSQL Hostname (RR)
RR0_DB_PORT	PostgreSQL Port (RR)	5432
RR0_DB_USER	PostgreSQL Username (RR)	nostr_ts_relay
RR0_DB_PASSWORD	PostgreSQL Password (RR)	nostr_ts_relay
RR0_DB_NAME	PostgreSQL Database name (RR)	nostr_ts_relay
RR0_DB_MIN_POOL_SIZE	Min. connections per worker (RR)	0
RR0_DB_MAX_POOL_SIZE	Max. connections per worker (RR)	3
RR0_DB_ACQUIRE_CONNECTION_TIMEOUT	New connection timeout (ms) (RR)	60000
RR1_DB_HOST	PostgresSQL Hostname (RR)
RR1_DB_PORT	PostgreSQL Port (RR)	5432
RR1_DB_USER	PostgreSQL Username (RR)	nostr_ts_relay
RR1_DB_PASSWORD	PostgreSQL Password (RR)	nostr_ts_relay
RR1_DB_NAME	PostgreSQL Database name (RR)	nostr_ts_relay
RR1_DB_MIN_POOL_SIZE	Min. connections per worker (RR)	0
RR1_DB_MAX_POOL_SIZE	Max. connections per worker (RR)	3
RR1_DB_ACQUIRE_CONNECTION_TIMEOUT	New connection timeout (ms) (RR)	60000
RRn_DB_HOST	PostgresSQL Hostname (RR)
RRn_DB_PORT	PostgreSQL Port (RR)	5432
RRn_DB_USER	PostgreSQL Username (RR)	nostr_ts_relay
RRn_DB_PASSWORD	PostgreSQL Password (RR)	nostr_ts_relay
RRn_DB_NAME	PostgreSQL Database name (RR)	nostr_ts_relay
RRn_DB_MIN_POOL_SIZE	Min. connections per worker (RR)	0
RRn_DB_MAX_POOL_SIZE	Max. connections per worker (RR)	3
RRn_DB_ACQUIRE_CONNECTION_TIMEOUT	New connection timeout (ms) (RR)	60000
TOR_HOST	Tor Hostname
TOR_CONTROL_PORT	Tor control Port	9051
TOR_PASSWORD	Tor control password	nostr_ts_relay
HIDDEN_SERVICE_PORT	Tor hidden service port	80
REDIS_URI	Redis URI (overrides REDIS_HOST, REDIS_PORT, etc.)
REDIS_HOST
REDIS_PORT	Redis Port	6379
REDIS_USER	Redis User	default
REDIS_PASSWORD	Redis Password	nostr_ts_relay
PROMETHEUS_URL	Prometheus base URL for admin metrics queries	http://127.0.0.1:9090
PROMETHEUS_QUERY_TIMEOUT_MS	Timeout for each Prometheus admin metrics query (ms)	5000
ADMIN_METRICS_SSE_INTERVAL_MS	Interval between /admin/metrics SSE snapshots (ms)	5000
ADMIN_METRICS_SNAPSHOT_TIMEOUT_MS	Timeout for collecting one /admin/metrics snapshot (ms)	10000
ADMIN_DEPENDENCY_PING_TIMEOUT_MS	Timeout for admin DB/Redis dependency pings (ms)	3000
GRAFANA_URL	Grafana base URL for admin dashboard embeds	http://127.0.0.1:7777
NOSTR_CONFIG_DIR	Configuration directory	<project_root>/.nostr/
MONITOR_PRIVATE_KEY	Hex-encoded private key for the NIP-66 monitor identity that will sign kind 30166/10166 events. Configure via environment variable, not settings.yaml.
DEBUG	Debugging filter
ZEBEDEE_API_KEY	Zebedee Project API Key
NWC_URL	NWC connection URL (nostr+walletconnect://...)

I2P

I2P support is provided as a sidecar container (i2pd) via docker-compose.i2p.yml, mirroring the Tor setup. No application-level environment variables are needed — the i2pd container creates an I2P server tunnel that forwards traffic to nostream's WebSocket port.

Configuration files live in the i2p/ directory:

File	Description
i2p/tunnels.conf	Defines the I2P server tunnel pointing at nostream (port 8008).
i2p/i2pd.conf	Minimal i2pd daemon configuration.

Tunnel keys are persisted at .nostr/i2p/data/ so the .b32.i2p address survives container restarts.

The i2pd web console (tunnel status, .b32.i2p destinations) is published to the host on 127.0.0.1:7070 only. Remove the ports: mapping in docker-compose.i2p.yml to disable host-side access.

• Start with I2P: nostream start --i2p

If you've set READ_REPLICAS to 4, you should configure RR0_ through RR3_.

Database indexes and benchmarking

The schema ships with a small, query-driven set of indexes. The most important ones for relay hot paths are:

Index	Covers
events_active_pubkey_kind_created_at_idx	REQ with authors+kinds ordered by created_at DESC, event_id ASC; hasActiveRequestToVanish; by-pubkey deletes. Composite key (event_pubkey, event_kind, event_created_at DESC, event_id) so the ORDER BY tie-breaker is satisfied from the index without a sort step.
events_deleted_at_partial_idx	Retention purge over soft-deleted rows. Partial on deleted_at IS NOT NULL.
invoices_pending_created_at_idx	findPendingInvoices poll (ORDER BY created_at ASC). Partial on status = 'pending'.
event_tags (tag_name, tag_value)	NIP-01 generic tag filters (#e, #p, #K, #I, …) via the normalized event_tags table. Both lowercase and uppercase single-letter tag filters are supported.
events_event_created_at_index	Time-range scans (since / until).
events_event_kind_index	Kind-only filters and purge kind-whitelist logic.

Run the read-only benchmark against your own database to confirm the planner is using the expected indexes and to record baseline latencies:

pnpm db:benchmark
pnpm db:benchmark --runs 5 --kind 1 --limit 500

The db:benchmark script loads the local .env file automatically (via node --env-file-if-exists=.env), using the same DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME variables as the relay. The benchmark issues only EXPLAIN (ANALYZE, BUFFERS) and SELECT statements — it never writes. Flags: --runs <n> (default 3), --kind <n> (default 1 / TEXT_NOTE; pass 0 for SET_METADATA), --limit <n> (default 500), --horizon-days <n> (default 7), --help.

For a full before/after proof of the index impact (seeds a throwaway dataset, drops and recreates the indexes, and prints a BEFORE/AFTER table), use:

pnpm db:verify-index-impact

The hot-path index migration (20260420_120000_add_hot_path_indexes.js) uses CREATE INDEX CONCURRENTLY, so it can be applied to a running relay without taking ACCESS EXCLUSIVE locks on the events or invoices tables.

Tag filter scope

Subscription filters support single-letter tag filters using the #<letter> key syntax (NIP-01). Both lowercase (#a–#z) and uppercase (#A–#Z) variants are accepted.

Scope	Examples	Usage
Lowercase (#a–#z)	#e, #p, #a, #k	Standard NIP-01 tag queries; parent-level references in NIP-22 comment threading
Uppercase (#A–#Z)	#E, #P, #A, #K, #I	Root-level references in NIP-22 comment threading and other NIPs that use uppercase to distinguish root vs. parent scope

NIP-22 comment threading (kind 1111): NIP-22 comment events use lowercase tags (#e, #a, #i, #k) to reference the immediate parent and uppercase tags (#E, #A, #I, #K) to reference the root item. Filters must therefore accept both cases to allow clients to query the full comment thread hierarchy. For example, to find all comments on a root event: {"kinds":[1111],"#E":["<root-event-id>"]}, or to find comments of a specific root kind: {"kinds":[1111],"#K":["1"]}.

Settings

Running nostream for the first time creates the settings file in <project_root>/.nostr/settings.yaml. If the file is not created and an error is thrown ensure that the <project_root>/.nostr folder exists. The configuration directory can be changed by setting the NOSTR_CONFIG_DIR environment variable. nostream will pick up any changes to this settings file without needing to restart.

The settings below are listed in alphabetical order by name. Please keep this table sorted when adding new entries.

Name	Description
admin.nip98.allowedPubkeys	Hex pubkeys allowed to use NIP-98 on the admin API. Empty means nobody (fail-closed). Defaults to [].
admin.nip98.enabled	Accept Authorization: Nostr (NIP-98) on protected admin API routes alongside session auth. Defaults to false. Clients must sign u using the HTTP(S) scheme and host derived from info.relay_url (ws/http → http, wss/https → https; never the request Host), plus the public path prefix and /admin/.... Successful auth events are one-time through created_at + maxSkewSeconds (Redis).
admin.nip98.maxSkewSeconds	Max skew in seconds between now and the auth event created_at. Replay claims last until that window ends (inclusive). Defaults to 60.
dvm.workers[].args	Arguments passed to the spawned command. Optional.
dvm.workers[].command	Command to spawn for this DVM worker (e.g. an interpreter or executable path).
dvm.workers[].kinds	NIP-90 job request kinds (5000-5999) this worker accepts. Optional.
dvm.workers[].timeoutMs	Max time in ms to wait for a job result before considering it timed out. Optional.
info.banner	Public banner image URL for the relay information document.
info.contact	Relay operator's contact. (e.g. mailto:operator@relay-your-domain.com)
info.description	Public description of your relay. (e.g. Toronto Bitcoin Group Public Relay)
info.icon	Public icon image URL for the relay information document.
info.name	Public name of your relay. (e.g. TBG's Public Relay)
info.pubkey	Relay operator's Nostr pubkey in hex format.
info.relay_url	Public-facing URL of your relay. (e.g. wss://relay.your-domain.com)
info.self	Optional. The relay's own signing pubkey (hex or npub1...), published as self in the relay information document. NIP-43 clients verify relay-signed events against it, so it must match the key the relay signs with. Leave unset to derive it from SECRET; run nostream info to print the derived value. A configured value that does not match disables kind 28935 invite requests.
info.terms_of_service	Public URL to relay terms of service.
limits.admissionCheck.ipWhitelist	List of IPs (IPv4 or IPv6) to ignore rate limits.
limits.admissionCheck.rateLimits[].period	Rate limit period in milliseconds.
limits.admissionCheck.rateLimits[].rate	Maximum number of admission checks during period.
limits.client.subscription.maxFilters	Maximum number of filters per subscription. Defaults to 10. Disabled when set to zero.
limits.client.subscription.maxSubscriptions	Maximum number of subscriptions per connected client. Defaults to 10. Disabled when set to zero.
limits.event.content[].kinds	List of event kinds to apply limit. Use [min, max] for ranges. Optional.
limits.event.content[].maxLength	Maximum length of content. Defaults to 1 MB. Disabled when set to zero.
limits.event.createdAt.maxNegativeDelta	Maximum number of seconds an event's created_at can be in the past. Defaults to zero. Disabled when set to zero.
limits.event.createdAt.maxPositiveDelta	Maximum number of seconds an event's created_at can be in the future. Defaults to 900 (15 minutes). Disabled when set to zero.
limits.event.eventId.minLeadingZeroBits	Leading zero bits required on every incoming event for proof of work. Defaults to zero. Disabled when set to zero.
limits.event.kind.blacklist	List of event kinds to always reject. Leave empty to allow any.
limits.event.kind.whitelist	List of event kinds to always allow. Leave empty to allow any.
limits.event.pubkey.blacklist	List of public keys to always reject. Public keys in this list will not be able to post to this relay.
limits.event.pubkey.minLeadingZeroBits	Leading zero bits required on the public key of incoming events for proof of work. Defaults to zero. Disabled when set to zero.
limits.event.pubkey.whitelist	List of public keys to always allow. Only public keys in this list will be able to post to this relay. Use for private relays.
limits.event.rateLimits[].kinds	List of event kinds rate limited. Use [min, max] for ranges. Optional.
limits.event.rateLimits[].period	Rate limiting period in milliseconds. For sliding_window: the time window during which requests are counted. For ewma: the half-life of the exponential decay — shorter values forget bursts faster, longer values are stricter on bursty clients.
limits.event.rateLimits[].rate	Maximum number of events during period.
limits.event.retention.kind.whitelist	Event kinds excluded from retention purge. NIP-62 REQUEST_TO_VANISH is always excluded from retention purge, even if not listed here.
limits.event.retention.maxDays	Maximum number of days to retain events. Purge deletes events that are expired (expires_at), soft-deleted (deleted_at), or older than this window (created_at). Any non-positive value disables retention purge.
limits.event.retention.pubkey.whitelist	Public keys excluded from retention purge.
limits.event.whitelists.ipAddresses	List of IPs (IPv4 or IPv6) to ignore rate limits.
limits.event.whitelists.pubkeys	List of public keys to ignore rate limits.
limits.invite.rateLimits[].period	Rate limit period in milliseconds for NIP-43 kind 28935 invite requests, counted per requesting pubkey.
limits.invite.rateLimits[].rate	Maximum number of invite requests a single pubkey may make during period. Each granted request writes a row to invite_codes, so this is the main defence against a code flood. Defaults to 5 per hour.
limits.message.ipWhitelist	List of IPs (IPv4 or IPv6) to ignore rate limits.
limits.message.rateLimits[].period	Rate limit period in milliseconds.
limits.client.subscription.maxSubscriptions	Maximum number of subscriptions per connected client. Defaults to 10. Disabled when set to zero.
limits.client.subscription.maxFilters	Maximum number of filters per subscription. Defaults to 10. Disabled when set to zero.
limits.message.rateLimits[].period	Rate limiting period in milliseconds. For sliding_window: the time window. For ewma: the half-life of the decay function.
limits.message.rateLimits[].rate	Maximum number of messages during period.
mirroring.static[].address	Address of mirrored relay. (e.g. ws://100.100.100.100:8008)
mirroring.static[].filters	Subscription filters used to mirror.
mirroring.static[].limits.event	Event limit overrides for this mirror. See configurations under limits.event.
mirroring.static[].secret	Secret to pass to relays. Nostream relays only. Optional.
mirroring.static[].skipAdmissionCheck	Disable the admission fee check for events coming from this mirror.
network.maxPayloadSize	Maximum number of bytes accepted per WebSocket frame
network.remoteIpHeader	HTTP header from proxy containing IP address from client.
nip05.domainBlacklist	List of domains blocked from NIP-05 verification. Authors with NIP-05 at these domains will be rejected.
nip05.domainWhitelist	List of domains allowed for NIP-05 verification. If set, only authors verified at these domains can publish.
nip05.maxConsecutiveFailures	Number of consecutive verification failures before giving up on an author. Defaults to 20.
nip05.mode	NIP-05 verification mode: enabled requires verification, passive verifies without blocking, disabled does nothing. Defaults to disabled.
nip05.verifyExpiration	Time in milliseconds before a successful NIP-05 verification expires and needs re-checking. Defaults to 604800000 (1 week).
nip05.verifyUpdateFrequency	Minimum interval in milliseconds between re-verification attempts for a given author. Defaults to 86400000 (24 hours).
nip42.authRequired	When true, clients must NIP-42 AUTH as the event author before publishing events. Advertised in NIP-11 as limitation.restricted_writes (not auth_required, which means AUTH before any connection action). Defaults to false.
nip42.sessionExpirySeconds	Seconds after which an authenticated pubkey must AUTH again on the same WebSocket. 0 (default) keeps the session for the connection lifetime.
nip42.restrictedReads.enabled	Enable NIP-42 auth-based read filtering. When enabled, events of the restricted kinds are only delivered to clients that have authenticated as the event's author or as a pubkey listed in the event's p tags. Applies to stored events (REQ), live broadcasts and COUNT queries. Subscriptions that exclusively target restricted kinds from unauthenticated clients are closed with an auth-required: reason. Defaults to false.
nip42.restrictedReads.kinds	List of event kinds (or [min, max] ranges) protected by auth-based read filtering. Defaults to [4, 1059] (NIP-04 encrypted direct messages and NIP-59 gift wraps).
nip43.enabled	Enable NIP-43 invite-based membership. When true, only admitted members may publish. Defaults to false.
nip43.inviteCodeExpirySeconds	Seconds until a newly minted invite code expires. 0 means the code never expires. Defaults to 600 (10 minutes).
nip43.defaultMaxUses	How many times a newly minted invite code can be claimed. Defaults to 1.
nip43.allowInviteRequests	Answer REQs for kind 28935 by minting an invite code on the fly and returning it as a relay-signed ephemeral event on that subscription. NIP-43 requires relays to opt in to this explicitly. Requesters must be authenticated via NIP-42, and info.self must match the relay's signing pubkey. Defaults to false.
nip43.inviteRequestWhitelist	Public keys allowed to request kind 28935 invite codes. Empty (the default) means any authenticated pubkey may request one; a non-empty list restricts minting to those pubkeys.
nip45.enabled	Enable or disable NIP-45 COUNT handling. Defaults to true.
nip50.enabled	Enable or disable NIP-50 full-text search. Defaults to false. When enabled, clients can include a search field in REQ filters to perform text queries against event content. Requires the GIN full-text index migration.
nip50.language	PostgreSQL text-search configuration name. Defaults to simple (language-agnostic tokenization). Set to english, spanish, etc. for stemming support. See PostgreSQL text search configurations. Note: The GIN index migration is built with the simple configuration. If you change this value, you must manually rebuild the index: DROP INDEX CONCURRENTLY events_content_fts_idx; CREATE INDEX CONCURRENTLY events_content_fts_idx ON events USING gin (to_tsvector('<your_language>', event_content)); — otherwise the planner cannot use the index and queries fall back to sequential scans.
nip50.maxQueryLength	Maximum length of the search query string. Queries exceeding this are truncated. Defaults to 256.
nip66.dnsCacheTtlSeconds	DNS cache TTL in seconds for repeated probe lookups of the same hostname. Defaults to 300.
nip66.enabled	Enable NIP-66 relay monitoring. When true, starts a relay-monitor cluster worker that probes targets on an interval and stores the latest snapshot in Redis. Defaults to false.
nip66.probeIntervalSeconds	Seconds between scheduled relay probe runs. Defaults to 3600.
nip66.targets	Public WebSocket URLs to probe (for example wss://relay.example.com). When empty, defaults to info.relay_url.
nip66.timeouts.dnsMs	DNS probe timeout in milliseconds. Defaults to 10000.
nip66.timeouts.nip11Ms	NIP-11 fetch timeout in milliseconds. Defaults to 10000.
nip66.timeouts.tlsMs	TLS probe timeout in milliseconds. Defaults to 10000.
nip66.timeouts.wsRttMs	WebSocket open RTT probe timeout in milliseconds. Defaults to 10000.
paymentProcessors.lnbits.baseURL	Base URL of your Lnbits instance.
paymentProcessors.lnbits.callbackBaseURL	Public-facing Nostream's Lnbits Callback URL. (e.g. https://relay.your-domain.com/callbacks/lnbits)
paymentProcessors.lnurl.invoiceURL	LUD-06 Pay Request provider URL. (e.g. https://getalby.com/lnurlp/your-username)
paymentProcessors.zebedee.baseURL	Zebedee's API base URL.
paymentProcessors.zebedee.callbackBaseURL	Public-facing Nostream's Zebedee Callback URL (e.g. https://relay.your-domain.com/callbacks/zebedee)
paymentProcessors.zebedee.ipWhitelist	List with Zebedee's API Production IPs. See ZBD API Documentation for more info.
payments.enabled	Enabled payments. Defaults to false.
payments.feeSchedules.admission[].amount	Admission fee amount in msats.
payments.feeSchedules.admission[].enabled	Enables admission fee. Defaults to false.
payments.feeSchedules.admission[].whitelists.event_kinds	List of event kinds to waive admission fee. Use [min, max] for ranges.
payments.feeSchedules.admission[].whitelists.pubkeys	List of pubkeys to waive admission fee.
payments.processor	Either zebedee, lnbits, lnurl.
workers.count	Number of workers to spin up to handle incoming connections.
	Spin workers as many CPUs are available when set to zero. Defaults to zero.
limits.message.ipWhitelist	List of IPs (IPv4 or IPv6) to ignore rate limits.
limits.admissionCheck.rateLimits[].period	Rate limiting period in milliseconds. For sliding_window: the time window. For ewma: the half-life of the decay function.
limits.admissionCheck.rateLimits[].rate	Maximum number of admission checks during period.
limits.admissionCheck.ipWhitelist	List of IPs (IPv4 or IPv6) to ignore rate limits.
limits.rateLimiter.strategy	Rate limiting strategy. Either ewma or sliding_window. Defaults to ewma. When using ewma, the period field in each rate limit serves as the half-life for the exponential decay function. Note: when switching from sliding_window to ewma, consider increasing rate values slightly as EWMA penalizes bursty behavior more aggressively.
mirroring.static[].address	Address of mirrored relay. (e.g. ws://100.100.100.100:8008)
mirroring.static[].filters	Subscription filters used to mirror.
mirroring.static[].limits.event	Event limit overrides for this mirror. See configurations under limits.event.
mirroring.static[].secret	Secret to pass to relays. Nostream relays only. Optional.
mirroring.static[].skipAdmissionCheck	Disable the admission fee check for events coming from this mirror.
network.maxPayloadSize	Maximum number of bytes accepted per WebSocket frame
network.remoteIpHeader	HTTP header from proxy containing IP address from client.
network.trustedProxies	Optional allow-list of proxy IPs allowed to set network.remoteIpHeader; otherwise socket remote IP is used.
nip05.domainBlacklist	List of domains blocked from NIP-05 verification. Authors with NIP-05 at these domains will be rejected.
nip05.domainWhitelist	List of domains allowed for NIP-05 verification. If set, only authors verified at these domains can publish.
nip05.maxConsecutiveFailures	Number of consecutive verification failures before giving up on an author. Defaults to 20.
nip05.mode	NIP-05 verification mode: enabled requires verification, passive verifies without blocking, disabled does nothing. Defaults to disabled.
nip05.verifyExpiration	Time in milliseconds before a successful NIP-05 verification expires and needs re-checking. Defaults to 604800000 (1 week).
nip05.verifyUpdateFrequency	Minimum interval in milliseconds between re-verification attempts for a given author. Defaults to 86400000 (24 hours).
paymentProcessors.lnbits.baseURL	Base URL of your Lnbits instance.
paymentProcessors.lnbits.callbackBaseURL	Public-facing Nostream's Lnbits Callback URL. (e.g. https://relay.your-domain.com/callbacks/lnbits)
paymentProcessors.lnurl.invoiceURL	LUD-06 Pay Request provider URL. (e.g. https://getalby.com/lnurlp/your-username)
paymentProcessors.zebedee.baseURL	Zebedee's API base URL.
paymentProcessors.zebedee.callbackBaseURL	Public-facing Nostream's Zebedee Callback URL (e.g. https://relay.your-domain.com/callbacks/zebedee)
paymentProcessors.zebedee.ipWhitelist	List with Zebedee's API Production IPs. See ZBD API Documentation for more info.
payments.enabled	Enabled payments. Defaults to false.
payments.feeSchedules.admission[].amount	Admission fee amount in msats.
payments.feeSchedules.admission[].enabled	Enables admission fee. Defaults to false.
payments.feeSchedules.admission[].whitelists.event_kinds	List of event kinds to waive admission fee. Use [min, max] for ranges.
payments.feeSchedules.admission[].whitelists.pubkeys	List of pubkeys to waive admission fee.
payments.processor	Either zebedee, lnbits, lnurl, nodeless, opennode, nwc.
workers.count	Number of workers to spin up to handle incoming connections. Spin workers as many CPUs are available when set to zero. Defaults to zero.