Parrhesia

Parrhesia is a Nostr relay server written in Elixir/OTP.

BETA CONDITION – BREAKING CHANGES MAY STILL HAPPEN!

Supported storage backends:

• PostgreSQL, which is the primary and production-oriented backend
• in-memory storage, which is useful for tests, local experiments, and benchmarks

Advanced Nostr features:

• Advanced Querying: Full-text search (NIP-50) and COUNT queries (NIP-45).
• Secure Messaging: First-class support for Marmot MLS-encrypted groups and NIP-17/44/59 gift-wrapped DMs.
• Identity & Auth: NIP-42 authentication flows and NIP-86 management API with NIP-98 HTTP auth.
• Data Integrity: Negentropy-based synchronization and NIP-62 vanish flows.
• Relay Sync Extension: Parrhesia-specific SYNC-PAGE keyset backfill for trusted relay-to-relay catch-up.

It exposes:

• listener-configurable WS/HTTP ingress, with a default public listener on port 4413
• a WebSocket relay endpoint at /relay by default on listeners that enable the nostr feature
• NIP-11 relay info on GET /relay by default with Accept: application/nostr+json
• operational HTTP endpoints such as /health, /ready, and /metrics by default on listeners that enable them
• a NIP-86-style management API at POST /management by default on listeners that enable the admin feature

Listeners can run in plain HTTP, HTTPS, mutual TLS, or proxy-terminated TLS modes. The current TLS implementation supports:

• server TLS on listener sockets
• optional client certificate admission with listener-side client pin checks
• proxy-asserted client TLS identity on trusted proxy hops
• admin-triggered certificate reload by restarting an individual listener from disk

Supported NIPs

Current supported_nips list:

1, 9, 11, 13, 17, 40, 42, 43, 44, 45, 50, 59, 62, 66, 70, 77, 86, 98

43 is advertised when the built-in NIP-43 relay access flow is enabled. Parrhesia generates relay-signed 28935 invite responses on REQ, validates join and leave requests locally, and publishes the resulting signed 8000, 8001, and 13534 relay membership events into its own local event store.

50 uses ranked PostgreSQL full-text search over event content by default. Parrhesia applies the filter limit after ordering by match quality, and falls back to trigram-backed substring matching for short or symbol-heavy queries such as search-as-you-type prefixes, domains, and punctuation-rich tokens.

66 is advertised when the built-in NIP-66 publisher is enabled and has at least one relay target. The default config enables it for the public relay URL. Parrhesia probes those target relays, collects the resulting NIP-11 / websocket liveness data, and then publishes the signed 10166 and 30166 events locally on this relay.

Parrhesia protocol extension: SYNC-PAGE

SYNC-PAGE is a Parrhesia-specific, non-NIP websocket frame for efficient relay-to-relay backfill. It pages stored events with (created_at, event_id) keyset cursors and can return batched EVENTS frames for high-volume catch-up. Parrhesia advertises support in NIP-11 as limitation.parrhesia_sync_page: true; workers only use it when a peer advertises that flag and otherwise fall back to standard REQ overlap sync. Operators can hide the advertisement with :features.parrhesia_sync_page / PARRHESIA_FEATURES_PARRHESIA_SYNC_PAGE.

See docs/sync.md for the wire shape and operational details.

Requirements

• Elixir ~> 1.18
• Erlang/OTP 28
• PostgreSQL (18 used in the dev environment; 16+ recommended)
• just for the command runner used in this repo
• Docker or Podman plus Docker Compose support if you want to run the published container image

Command runner (just)

This repo includes a justfile that provides a grouped command/subcommand CLI over common mix tasks and scripts.

just
just help bench
just help e2e

Run locally

1) Prepare the database

Parrhesia uses these defaults in dev:

• PGDATABASE=parrhesia_dev
• PGHOST=localhost
• PGPORT=5432
• PGUSER=$USER

Create the DB and run migrations/seeds:

mix setup

2) Start the server

mix run --no-halt

The default public listener binds to http://localhost:4413.

WebSocket clients should connect to:

ws://localhost:4413/relay

Useful endpoints

• GET /health -> ok by default
• GET /ready -> readiness status by default
• GET /metrics -> Prometheus metrics by default (private/loopback source IPs by default)
• GET /relay + Accept: application/nostr+json -> NIP-11 document by default
• POST /management -> management API by default (requires NIP-98 auth)

Test suites

Primary test entrypoints:

• mix test for the ExUnit suite
• just e2e for the local e2e set plus the Docker three-node gap sync suite
• just e2e marmot for the Marmot client end-to-end suite
• just e2e node-sync for the two-node relay sync end-to-end suite
• just e2e node-sync-docker for the release-image Docker two-node relay sync suite
• just e2e node-sync-three-node-docker for the high-volume three-node gap sync suite

The node-sync harnesses are driven by:

• scripts/run_node_sync_e2e.sh
• scripts/run_node_sync_docker_e2e.sh
• scripts/node_sync_e2e.exs
• compose.node-sync-e2e.yaml

just e2e node-sync runs two real Parrhesia nodes against separate PostgreSQL databases, verifies catch-up and live sync, restarts one node, and verifies persisted resume behavior. just e2e node-sync-docker runs the same scenario against the release Docker image. just e2e node-sync-three-node-docker exercises high-volume paged relay sync across a three-node gap topology.

GitHub CI currently runs the non-Docker node-sync e2e on the main Linux matrix job. The Docker node-sync e2e remains an explicit/manual check because it depends on release-image build/runtime fidelity and a working Docker host.

Embedding in another Elixir app

Parrhesia is usable as an embedded OTP dependency, not just as a standalone relay process. The intended in-process surface is Parrhesia.API.*, especially:

• Parrhesia.API.Events for publish, query, and count
• Parrhesia.API.Stream for local REQ-like subscriptions
• Parrhesia.API.Admin for management operations
• Parrhesia.API.Identity, Parrhesia.API.ACL, and Parrhesia.API.Sync for relay identity, protected sync ACLs, and outbound relay sync

For host-managed HTTP/WebSocket ingress mounting, use Parrhesia.Plug.

Start with:

• docs/local_api.md for the embedding model and a minimal host setup
• generated ExDoc for the Embedded API module group when running mix docs

Important caveats for host applications:

• Parrhesia is beta software; expect some API and config churn as the runtime stabilizes.
• Parrhesia currently assumes a single runtime per BEAM node and uses globally registered process names.
• The defaults in this repo's config/*.exs are not imported automatically when Parrhesia is used as a dependency. A host app must set config :parrhesia, ... explicitly.
• The host app is responsible for migrating Parrhesia's schema, for example with Parrhesia.Release.migrate() or mix ecto.migrate -r Parrhesia.Repo.

Official embedding boundary

For embedded use, the stable boundaries are:

• Parrhesia.API.* for in-process publish/query/admin/sync operations
• Parrhesia.Plug for host-managed HTTP/WebSocket ingress mounting

If your host app owns the public HTTPS endpoint, keep this as the baseline runtime config:

config :parrhesia, :listeners, %{}

Notes:

• listeners: %{} disables Parrhesia-managed HTTP/WebSocket ingress (/relay, /management, /metrics, etc.).
• Mount Parrhesia.Plug in your host endpoint/router when you still want Parrhesia ingress under the host's single HTTPS surface.
• Parrhesia.Web.* modules remain internal runtime wiring. Use Parrhesia.Plug as the documented mount API.

The config reference below still applies when embedded. That is the primary place to document basic setup and runtime configuration changes.

Production configuration

Minimal setup

Before a Nostr client can publish its first event successfully, make sure these pieces are in place:

1. PostgreSQL is reachable from Parrhesia. Set DATABASE_URL and create/migrate the database with Parrhesia.Release.migrate() or mix ecto.migrate.

   PostgreSQL is the supported production datastore. The in-memory backend is intended for non-persistent runs such as tests and benchmarks.

2. Parrhesia listeners are configured for your deployment. The default config exposes a public listener on plain HTTP port 4413, and a reverse proxy can terminate TLS and forward WebSocket traffic to /relay. Additional listeners can be defined in config/*.exs.

3. :relay_url matches the public relay URL clients should use. Set PARRHESIA_RELAY_URL to the public relay URL exposed by the reverse proxy. In the normal deployment model, this should be your public wss://.../relay URL.

4. The database schema is migrated before starting normal traffic. The app image does not auto-run migrations on boot.

That is the actual minimum. With default policy settings, writes do not require auth, event signatures are verified, and no extra Nostr-specific bootstrap step is needed before posting ordinary events.

In prod, these environment variables are used:

• DATABASE_URL (required), e.g. ecto://USER:PASS@HOST/parrhesia_prod
• POOL_SIZE (optional, default 32)
• PORT (optional, default 4413)
• PARRHESIA_* runtime overrides for relay config, metadata, identity, sync, ACL, limits, policies, listeners, retention, and features
• PARRHESIA_EXTRA_CONFIG (optional path to an extra runtime config file)

config/runtime.exs reads these values at runtime in production releases.

Runtime env naming

For runtime overrides, use the PARRHESIA_... prefix:

• PARRHESIA_RELAY_URL
• PARRHESIA_METADATA_HIDE_VERSION
• PARRHESIA_RELAY_IDENTITY_*
• PARRHESIA_NODE_IDENTITY_*
• PARRHESIA_SYNC_*
• PARRHESIA_ACL_*
• PARRHESIA_TRUSTED_PROXIES
• PARRHESIA_PUBLIC_MAX_CONNECTIONS
• PARRHESIA_MODERATION_CACHE_ENABLED
• PARRHESIA_ENABLE_EXPIRATION_WORKER
• PARRHESIA_ENABLE_PARTITION_RETENTION_WORKER
• PARRHESIA_STORAGE_BACKEND
• PARRHESIA_LIMITS_*
• PARRHESIA_POLICIES_*
• PARRHESIA_METRICS_*
• PARRHESIA_METRICS_ENDPOINT_MAX_CONNECTIONS
• PARRHESIA_RETENTION_*
• PARRHESIA_FEATURES_*
• PARRHESIA_METRICS_ENDPOINT_*

Examples:

export PARRHESIA_POLICIES_AUTH_REQUIRED_FOR_WRITES=true
export PARRHESIA_METRICS_ALLOWED_CIDRS="10.0.0.0/8,192.168.0.0/16"
export PARRHESIA_LIMITS_OUTBOUND_OVERFLOW_STRATEGY=drop_oldest

Listeners themselves are primarily configured under config :parrhesia, :listeners, .... The current runtime env helpers tune the default public listener and the optional dedicated metrics listener, including their connection ceilings.

For settings that are awkward to express as env vars, mount an extra config file and set PARRHESIA_EXTRA_CONFIG to its path inside the container.

Config reference

CSV env vars use comma-separated values. Boolean env vars accept 1/0, true/false, yes/no, or on/off.

Parrhesia supports role-based server identities. Normal relay use defaults to the :relay role; sync workers use :node for NIP-42 peer authentication when that role is configured.

config :parrhesia, :identities,
  relay: [private_key: shared_relay_private_key],
  node: [private_key: per_node_private_key]

Top-level :parrhesia

Parrhesia.Repo

Parrhesia.ReadRepo

:listeners

Listener max_connections is a first-class config field. Parrhesia translates it to ThousandIsland's per-acceptor num_connections limit based on the active acceptor count. Raw bandit_options[:thousand_island_options] can still override that for advanced tuning.

Listener transport.tls supports :disabled, :server, :mutual, and :proxy_terminated. For TLS-enabled listeners, the main config-file fields are certfile, keyfile, optional cacertfile, optional cipher_suite, optional client_pins, and proxy_headers for proxy-terminated identity.

Every listener supports this config-file schema:

Listener path overrides must be non-empty absolute paths and must be unique within a listener. | :auth.nip42_required | - | false | Require NIP-42 for relay reads / writes | | :auth.nip98_required_for_admin | PARRHESIA_POLICIES_MANAGEMENT_AUTH_REQUIRED on public | true | Require NIP-98 for management API calls | | :identity_role | - | :relay | Identity role advertised in NIP-11 for this listener | | :baseline_acl.read | - | [] | Static read deny/allow rules | | :baseline_acl.write | - | [] | Static write deny/allow rules | | :read_protected_mode | - | :sanitize on public, :deny otherwise | Read handling for protected surfaces (:deny closes, :sanitize excludes protected subsets) | | :limits.max_filter_limit | - | global :limits.max_filter_limit | Per-listener cap for REQ initial replay and SYNC-PAGE page size; accepts :infinity in config files | | :limits.max_query_candidates | - | global :limits.max_query_candidates | Per-listener query candidate cap for REQ initial replay; accepts :infinity in config files | | :bandit_options | - | [] | Advanced Bandit / ThousandIsland passthrough |

:nip66

NIP-66 targets are probe sources, not publish destinations. Parrhesia connects to each target relay, collects the configured liveness / discovery data, and stores the resulting signed 10166 / 30166 events in its own local event store so clients can query them here.

:nip43

Parrhesia treats NIP-43 invite requests as synthetic relay output, not stored client input. A REQ for kind 28935 causes the relay to generate a fresh relay-signed invite event on the fly. Clients then submit that claim back in a protected kind 28934 join request. When a join or leave request is accepted, Parrhesia updates its local relay membership state and publishes the corresponding relay-signed 8000 / 8001 delta plus the latest 13534 membership snapshot locally.

:limits

:policies

Listener-related Metrics Helpers

:retention

:features

:verify_event_signatures is config-file only. Production releases always verify event signatures.

Extra runtime config

Deploy

Option A: Elixir release

export MIX_ENV=prod
export DATABASE_URL="ecto://USER:PASS@HOST/parrhesia_prod"
export POOL_SIZE=20

mix deps.get --only prod
mix compile
mix release

_build/prod/rel/parrhesia/bin/parrhesia eval "Parrhesia.Release.migrate()"
_build/prod/rel/parrhesia/bin/parrhesia start

For systemd/process managers, run the release command with start.

Option B: Nix release package (default.nix)

Build:

nix build

Run the built release from ./result/bin/parrhesia (release command interface).

Option C: Docker image via Nix flake

Build the image tarball:

nix build .#dockerImage
# or with explicit build target:
nix build .#packages.x86_64-linux.dockerImage

Load it into Docker:

docker load < result

Run database migrations:

docker run --rm \
  -e DATABASE_URL="ecto://USER:PASS@HOST/parrhesia_prod" \
  parrhesia:latest \
  eval "Parrhesia.Release.migrate()"

Start the relay:

docker run --rm \
  -p 4413:4413 \
  -e DATABASE_URL="ecto://USER:PASS@HOST/parrhesia_prod" \
  -e POOL_SIZE=20 \
  parrhesia:latest

Option D: Docker Compose with PostgreSQL

The repo includes compose.yaml and .env.example so Docker users can run Postgres and Parrhesia together.

Set up the environment file:

cp .env.example .env

If you are building locally from source, build and load the image first:

nix build .#dockerImage
docker load < result

Then start the stack:

docker compose up -d db
docker compose run --rm migrate
docker compose up -d parrhesia

The relay will be available on:

ws://localhost:4413/relay

Notes:

• compose.yaml keeps PostgreSQL in a separate container; the Parrhesia image only runs the app release.
• The container listens on port 4413; use PARRHESIA_HOST_PORT if you want a different published host port.
• Migrations are run explicitly through the one-shot migrate service instead of on every app boot.
• Common runtime overrides can go straight into .env; see .env.example for examples.
• For more specialized overrides, mount a file and set PARRHESIA_EXTRA_CONFIG=/path/in/container/runtime.exs.
• When a GHCR image is published, set PARRHESIA_IMAGE=ghcr.io/<owner>/parrhesia:<tag> in .env and reuse the same compose flow.

Benchmark

The benchmark compares two Parrhesia profiles, one backed by PostgreSQL and one backed by the in-memory adapter, against strfry and nostr-rs-relay using nostr-bench. The cloud benchmark target set also includes nostream and Haven. Benchmark runs also lift Parrhesia's relay-side limits by default so the benchmark client, not server guardrails, is the main bottleneck.

just bench compare is a sequential mixed-workload benchmark, not an isolated per-endpoint microbenchmark. Each relay instance runs connect, then echo, then event, then req against the same live process, so later phases measure against state and load created by earlier phases.

Run it with:

just bench compare

Cloud benchmark (Hetzner Cloud)

For distributed runs (one server node + multiple client nodes), use:

just bench cloud
# or: ./scripts/run_bench_cloud.sh

or invoke the orchestrator directly:

node scripts/cloud_bench_orchestrate.mjs

Prerequisites:

• hcloud CLI installed
• Hetzner Cloud token exported as HCLOUD_TOKEN
• local docker, git, ssh, and scp available

Example:

export HCLOUD_TOKEN=...
just bench cloud-quick
# or: ./scripts/run_bench_cloud.sh --quick

Outputs:

• raw client logs per run: bench/cloud_artifacts/<run_id>/...
• JSONL history entries (local + cloud): bench/history.jsonl

Useful history/render commands:

# List available machines and runs in history
just bench list

# Regenerate chart + README table for a machine
just bench update <machine_id>

# Regenerate from all machines
just bench update all

Current comparison results:

Higher is better for ↑ metrics. Lower is better for ↓ metrics.

(Results from a Linux container on a 6-core Intel i5-8400T with NVMe drive, PostgreSQL 18)

Development quality checks

Before opening a PR:

mix precommit

Additional external CLI end-to-end checks with nak:

just e2e nak

For Marmot client end-to-end checks (TypeScript/Node suite using marmot-ts, included in precommit):

just e2e marmot