A lightweight, community-focused Nostr relay with whitelist support and a full CLI. Single binary, SQLite storage, pure Go (no CGO), easy to self-host. Only whitelisted pubkeys can write; everyone can read.
- Whitelist-based — only approved pubkeys can publish events
- SQLite storage — single file database, WAL mode, pure Go driver
- Full-text search — NIP-50 search via SQLite FTS5
- NIP-42 authentication — challenge-response auth for write access
- Event expiration — automatic cleanup of expired events (NIP-40)
- Event deletion — NIP-09 deletion support
- Public channels — NIP-28 channel support (kinds 40-44)
- CLI management — add/remove users, view stats, backup/restore
- Systemd ready — built-in daemon setup command
- Tiny footprint — single binary under 15MB
go install github.com/xdamman/nostr-relay@latest
nostr-relay setup admin npub1your...pubkey
nostr-relay startgit clone https://github.com/xdamman/nostr-relay.git
cd nostr-relay
make build-small
./nostr-relay versionnostr-relay start [--port 3334] [--db ./nostr-relay.db] # Start relay
nostr-relay stop # Stop relay
nostr-relay version # Show versionnostr-relay setup # Interactive setup
nostr-relay setup admin <npub> # Set admin pubkey
nostr-relay setup daemon # Install systemd servicenostr-relay allow <npub> # Add pubkey to whitelist
nostr-relay disallow <npub> # Remove pubkey from whitelistnostr-relay stats [--format json] # Relay statistics
nostr-relay users [-n 20] # List users by activity
nostr-relay requests [-n 10] # Recent REQ subscriptionsnostr-relay dump [--output backup.sql] # Dump database
nostr-relay restore <dump_file> # Restore from dumpConfiguration is stored in the SQLite database (config table):
| Key | Description |
|---|---|
admin_pubkey |
Admin's hex pubkey (always whitelisted) |
relay_name |
Relay name shown in NIP-11 |
relay_description |
Relay description shown in NIP-11 |
Set via nostr-relay setup or nostr-relay setup admin <npub>.
| NIP | Description |
|---|---|
| NIP-01 | Basic protocol flow (EVENT, REQ, CLOSE, EOSE, OK, NOTICE) |
| NIP-02 | Follow lists (kind 3) |
| NIP-04 | Encrypted DMs (kind 4) — store and relay |
| NIP-09 | Event deletion (kind 5) |
| NIP-11 | Relay information document |
| NIP-15 | End of Stored Events Notice |
| NIP-20 | Command results (OK messages) |
| NIP-28 | Public channels (kinds 40-44) |
| NIP-40 | Expiration timestamp |
| NIP-42 | Authentication |
| NIP-50 | Search |
nostr-relay/
├── main.go # Entry point, CLI routing
├── relay/
│ ├── server.go # WebSocket server, HTTP handler, NIP-11
│ ├── handler.go # Message handling (EVENT, REQ, CLOSE, AUTH)
│ ├── filter.go # Subscription filter matching
│ └── auth.go # NIP-42 authentication
├── store/
│ ├── sqlite.go # SQLite storage engine
│ ├── whitelist.go # Whitelist management
│ └── migrate.go # Schema migrations
├── nostr/
│ ├── event.go # Event struct, ID/signature verification
│ ├── keys.go # npub/hex bech32 conversion
│ └── filter.go # Filter struct and matching
└── cmd/
├── serve.go # start/stop commands
├── allow.go # allow/disallow commands
├── setup.go # setup command
├── stats.go # stats command
├── users.go # users command
├── requests.go # requests command
├── dump.go # dump/restore commands
└── help.go # help text
MIT