Wisp

A fast, lightweight Nostr relay written in Zig.

Wisp is a single-binary Nostr relay built for speed and simplicity. One command runs your personal relay, automatically syncing notes from the people you follow.

Why Wisp?

• Fast — 2x higher throughput than strfry, 10x lower latency.
• Small — single 1.2MB binary, ~15MB RAM at idle.
• Simple — one command to run your personal relay with your feed.
• Spider Mode — automatically syncs events from people you follow.

Features

• NIPs: 1, 2, 9, 11, 13, 16, 33, 40, 42, 45, 50, 65, 70, 77, 86
• LMDB storage (no external database)
• Spider mode for syncing events from external relays
• Import/export to JSONL

Where to start

• Installation — Docker, build from source, and import/export.
• Configuration — wisp.toml and WISP_-prefixed environment variables.
• Deployment — exposing your relay publicly over wss:// with Caddy.
• Benchmarks — throughput and latency versus strfry.
• Contributing — reporting issues and submitting pull requests.

Project links

• Source: https://github.com/privkeyio/wisp
• License: MIT

Installation

Quickstart

Docker

docker run -d -p 127.0.0.1:7777:7777 -v wisp-data:/data ghcr.io/privkeyio/wisp --spider-admin npub1yourkey...

Build from source

Download the latest release or build from source:

# 1. Install dependencies (requires Zig 0.15+)
sudo apt install -y liblmdb-dev libsecp256k1-dev libssl-dev

# 2. Build
git clone https://github.com/privkeyio/wisp && cd wisp
zig build -Doptimize=ReleaseFast

# 3. Run (replace with your npub)
./zig-out/bin/wisp --spider-admin npub1yourkey...

That’s it. Wisp will fetch your follow list, sync notes from popular relays, and serve them at ws://localhost:7777. Add this relay URL to your Nostr client.

For more options, see Configuration.

Import / Export

Wisp reads and writes events as JSONL, so backups and migrations are a single command:

./zig-out/bin/wisp export > backup.jsonl
./zig-out/bin/wisp import < backup.jsonl

Configuration

Wisp reads configuration from several sources, applied in order, each overriding the last:

1. Built-in defaults (shown in the tables below).
2. A TOML file, if you pass one: wisp relay wisp.toml.
3. Environment variables (WISP_*), which override the file.
4. A few CLI flags (--spider-admin, --db), which override everything for the settings they touch.

So an environment variable always wins over the same setting in the TOML file. Copy wisp.toml.example to wisp.toml to start from an annotated template.

WISP_PORT=8080 ./zig-out/bin/wisp

Command line

wisp [command] [config.toml]

Commands:
  relay [config]   Start the relay server (default if omitted)
  import           Import events from stdin (JSONL)
  export           Export all events to stdout (JSONL)
  help             Show help

Flags:
  --spider-admin <npub|hex>   Enable spider mode and follow this pubkey's contacts
  --db <path>                 Database path for import/export (default ./data)

The relay’s storage path comes from [storage] path / WISP_STORAGE_PATH. --db applies to the import and export commands only. --spider-admin accepts an npub (decoded to hex), unlike the file/env spider settings which expect raw hex.

Settings

Each setting lists its TOML key (under its [section]), its environment variable, type, and default. Settings with no environment variable are configurable only via the TOML file.

[server]

[relay] (NIP-11 metadata)

[storage]

Warning: /dev/shm is volatile tmpfs — all data is lost on reboot. Use it only for benchmarks or disposable caches. For production, point path at persistent storage and/or configure backups.

Durability

sync controls how aggressively LMDB flushes to disk on each commit, trading throughput for crash safety:

In the durable modes (meta/full) writes go through a group-commit writer thread: events that arrive close together are committed in one transaction, so a batch pays a single fsync rather than one per event. Throughput therefore scales with how many clients publish concurrently.

The default is meta: it never corrupts the database and at worst loses the last transaction on a crash. Use full when no acknowledged write may ever be lost, or none for maximum throughput on a relay where the data is disposable (a cache or benchmark) and a crash may corrupt the database. none uses a faster synchronous write path, since there is no fsync to amortize.

[limits]

[rate_limits]

[timeouts]

[auth] (NIP-42)

[security]

IP list entries match exactly unless they end in . (IPv4 prefix) or : (IPv6 prefix), e.g. 10.0.0. matches 10.0.0.0–10.0.0.255. CIDR notation and * wildcards are not supported.

[spider]

[negentropy] (NIP-77)

[management] (NIP-86)

Spider mode

Spider mode keeps your relay populated by syncing events from the people you follow. Set admin to your hex pubkey (or pass --spider-admin npub1... on the CLI) and Wisp fetches your contact list and mirrors their notes from the configured relays:

[spider]
enabled = true
relays = "wss://relay.damus.io,wss://nos.lol,wss://relay.nostr.band"
sync_interval = 300
admin = ""  # your hex pubkey

Monitoring

Operational metrics are served in Prometheus format at GET /metrics on the relay port: connection counts, events stored/rejected/broadcast, REQ totals, and rate-limit counters. The endpoint honors ip_whitelist/ip_blacklist, so restrict it there or at your reverse proxy/firewall if it should not be public.

Deployment

To make your relay publicly accessible with TLS, run Wisp behind Caddy, which provisions and renews certificates automatically.

# Run wisp
docker run -d --restart always -p 127.0.0.1:7777:7777 -v wisp-data:/data \
  ghcr.io/privkeyio/wisp --spider-admin npub1yourkey...

# Install Caddy for automatic TLS
sudo apt install -y caddy

Create /etc/caddy/Caddyfile:

relay.yourdomain.com {
    reverse_proxy localhost:7777
}

Reload Caddy:

sudo systemctl restart caddy

Your relay is now live at wss://relay.yourdomain.com.

Behind a proxy: set trust_proxy = true in the [security] section of wisp.toml so per-IP connection limits and IP allow/deny lists see the real client IP from Caddy’s X-Forwarded-For header instead of 127.0.0.1.

Benchmarks

Peak write throughput, all relays at 100% delivery:

Measured with nostr-bench: 5,000 events x 4 workers at peak rate (--rate 0), native release builds on a 16-core Linux host, with the event-rate limit raised. RssAnon sampled during the run; figures are representative of three stable iterations.

This is peak write capability with Wisp in sync = none (non-durable). Wisp’s default is sync = meta (durable, never corrupts), which trades raw throughput for crash safety; in the durable modes throughput scales with publisher concurrency because writes are group-committed (see Configuration). strfry and nostr-rs-relay write durably by default, so a fair durable-vs-durable comparison runs Wisp in meta/full. On throughput and p99 latency Wisp leads; strfry stays smallest in memory.

Contributing

Contributions are welcome. Wisp’s guiding principles are fast, lightweight, and simple — feature requests and changes should align with those goals.

See CONTRIBUTING.md for the full guidelines, including the issue policy, branch naming, commit conventions, the NIP implementation policy, and development setup.

Development setup

# Install dependencies (Ubuntu/Debian)
sudo apt install -y liblmdb-dev libsecp256k1-dev libssl-dev

# Clone and build
git clone https://github.com/privkeyio/wisp && cd wisp
zig build

# Run tests
zig build test

# Build optimized release
zig build -Doptimize=ReleaseFast

# Format code
zig fmt src/*.zig