Everyone can read. Only people who paid a small one-time fee in Monero can publish.
- Try it: https://xmr.usenostr.org
- Add it to your relay list:
wss://xmr.usenostr.org
- Features
- How it works
- Self-hosting
- Configuration
- Administration
- Monitoring and alerts
- Backups
- Upgrading
- Migrating from nerostr v1 (strfry)
- Development
- Known nerostr relays
- One binary, one port. Relay, paywall and admin API in a single Go program built on khatru, with LMDB for events and SQLite for members.
- Private payments. Every invoice gets a fresh Monero subaddress. A view-only wallet is enough, so the server never holds your spend key.
- Payments that don't get lost. Partial payments add up, and payments that arrive after an invoice expired are still credited (for 30 days by default).
- Members stay reachable. Anyone can reply to, react to, zap and DM a member here, while the relay's feed shows members' posts only.
- A welcome DM to every new member, from the relay's own key (customizable).
- Alerts on nostr. The relay DMs you when payments stop being processed (wallet unreachable or stuck) and when they recover. An optional heartbeat URL catches full outages.
- Standard nostr integration.
- NIP-11 advertises the admission fee and payment page, so clients can show it.
- NIP-86 lets you manage members, bans and blocked IPs from any NIP-86 client, authenticated with your nostr key.
- Also supported: NIP-09 deletions, NIP-40 expiration, NIP-42 auth, NIP-45 counts, NIP-70 protected events and NIP-77 negentropy sync.
- Hardened by default.
- Per-IP and per-key rate limits, with trusted-proxy aware client IPs.
- A flood guard that stops a looping bot or bridge from reposting the same note.
- A strict Content-Security-Policy.
- Non-root, read-only containers.
- The wallet RPC sits on an internal network behind a password.
- A simple UI. No JavaScript required. With JavaScript you also get live payment status, copy buttons and login with a NIP-07 browser extension.
- A user enters their public key (npub or hex) on the relay's web page.
- nerostr asks
monero-wallet-rpcfor a new subaddress and shows it with the amount and a QR code. - Every 20 seconds nerostr checks the wallet for transfers to open invoices.
Once the received amount has enough confirmations (
MIN_CONFIRMATIONS, default 1), the key becomes a member. - Members can publish. Everyone else gets
restricted: pay the one-time admission fee at https://…from the relay, which most clients show to the user.
Reading is always free. Former members can still delete their own events.
Top-level notes that repeat the author's own text are refused with duplicate:. A repeat means the same text was
seen less than an hour before, counting refused copies too, so a stuck bot stays blocked until it pauses.
Replies are never affected, so answering many people with the same "Good morning!" is fine.
With INBOX=true (the default), non-members can also publish events that tag a member, as long as the kind is in INBOX_KINDS.
The defaults cover replies, legacy and NIP-17 DMs, reposts, reactions, comments and zap receipts.
That way members can be reached here without a separate inbox relay. Members can list this relay in their NIP-17 DM relay list (kind 10050).
To keep the paid feed clean, events from non-members are only returned to queries that ask for something specific:
an ids or authors filter, or a #p, #e, #a or #q tag (notifications, threads, DMs).
They never appear in general feed queries or live feed subscriptions.
Inbox events are rate-limited per IP and may tag at most 20 people.
You need a small Linux server with Docker, a domain, and a Monero wallet.
-
Get the files:
git clone https://github.com/pluja/nerostr && cd nerostr cp example.env .env mkdir -p data/nerostr data/wallet
-
Put a wallet in
data/wallet/. Use a view-only wallet: it can create subaddresses and see incoming payments, but cannot spend. You can create one from your main wallet's address and private view key, for example withmonero-wallet-cli --generate-from-view-keyor Feather Wallet. You need<name>and<name>.keys, plus the password in a file:cp /path/to/nerostr_wallet /path/to/nerostr_wallet.keys data/wallet/ printf '%s' 'your wallet password' > data/wallet/password chmod 600 data/wallet/password sudo chown -R 1000:1000 data # both containers run as uid 1000
-
Edit
.env. At least setPUBLIC_URL,MONERO_WALLET_FILENAME,MONERO_DAEMON_ADDRESS, and a randomMONERO_WALLET_RPC_PASSWORD(openssl rand -hex 32). Every option is documented inexample.env. -
Start it:
docker compose up -d docker compose logs -f nerostr
-
Put a TLS reverse proxy in front of
127.0.0.1:8080. Web pages, websockets, NIP-11 and NIP-86 all go to the same upstream:- Caddy:
reverse_proxy 127.0.0.1:8080 - nginx
- caddy-docker-proxy: copy it to
docker-compose.override.ymland set your domain.
- Caddy:
Check https://your.domain/healthz. It reports the database status, and whether payments are being processed.
Then set up alerts, so you hear about problems before your users do.
Your own monerod is best for privacy and reliability. A pruned node needs about 100 GB of disk.
A remote node works, but it learns which transactions your wallet is interested in.
Pick a reputable one; xmrlist.com and monero.fail list public nodes.
Configuration is read from environment variables (.env with Docker Compose).
| Variable | Default | Meaning |
|---|---|---|
PUBLIC_URL |
(required) | Public origin, e.g. https://xmr.example.com. NEROSTR_HOST=<host> also works. |
ADMISSION_AMOUNT |
0.002 |
One-time fee in XMR. |
MIN_CONFIRMATIONS |
1 |
Confirmations before access is granted. 0 accepts mempool payments. |
INVOICE_EXPIRE_TIME |
3600 |
Seconds before an invoice is replaced by a new one. |
LATE_PAYMENT_WINDOW |
2592000 |
Seconds during which payments to expired invoices still count. |
ADMIN_PUBKEYS |
Comma-separated npubs allowed to use the NIP-86 management API. | |
RELAY_NAME, RELAY_DESCRIPTION, RELAY_PUBKEY, RELAY_CONTACT, RELAY_ICON |
NIP-11 relay information. | |
MONERO_WALLET_RPC_URL |
http://monero-wallet-rpc:18083/json_rpc |
Wallet RPC endpoint. |
MONERO_WALLET_RPC_USER, MONERO_WALLET_RPC_PASSWORD |
Digest auth for the wallet RPC (set by the compose file). | |
MAX_OPEN_INVOICES |
500 |
Cap on unpaid, unexpired invoices. |
PAYMENT_POLL_INTERVAL |
20 |
Seconds between wallet checks. |
TRUSTED_PROXIES |
private ranges | Sources whose X-Forwarded-For is trusted. |
API_KEY |
Enables the v1 X-API-KEY endpoints (see below). |
|
INBOX, INBOX_KINDS |
true, 1,4,6,7,16,1059,1111,9735 |
Accept events from non-members that tag a member (Inbox). |
ALERT_PUBKEYS, ALERT_AFTER, ALERT_RELAYS |
admins, 600, popular relays |
Who gets alert DMs, after how many seconds of trouble, and where to find their DM relays. |
HEARTBEAT_URL, HEARTBEAT_INTERVAL |
, 300 |
URL requested periodically while healthy (dead-man switch). |
WELCOME_MESSAGE |
a short welcome | DMed to every key that just paid, from the relay's own key. Supports {name}, {relay} and {url}; off disables it. |
RELAY_SECRET_KEY |
generated | The relay's own nostr key (signs alerts, NIP-11 self). Kept in data/nerostr/relay.key if not set. |
DATA_DIR, LISTEN_ADDR, LOG_LEVEL |
/data, :8080, info |
Add your npub to ADMIN_PUBKEYS and restart. Then use any NIP-86 client, or nak:
nak admin allowpubkey --sec <your nsec> --pubkey <hex> --reason "friend" wss://xmr.example.com
nak admin banpubkey --sec <your nsec> --pubkey <hex> --reason "spam" wss://xmr.example.com
nak admin listallowedpubkeys --sec <your nsec> wss://xmr.example.com| Method | Effect |
|---|---|
allowpubkey / unallowpubkey / listallowedpubkeys |
Grant, revoke or list membership. Allowing a key also lifts its ban. |
banpubkey / unbanpubkey / listbannedpubkeys |
A ban revokes membership, blocks publishing (even after paying) and deletes the key's events. |
banevent / allowevent / listbannedevents |
Delete an event and refuse it if it is sent again. |
blockip / unblockip / listblockedips |
Refuse websocket connections from an IP. |
If API_KEY is set, the v1 endpoints keep working:
curl -X POST -H "X-API-KEY: $API_KEY" https://xmr.example.com/api/user/<npub or hex>
curl -X DELETE -H "X-API-KEY: $API_KEY" https://xmr.example.com/api/user/<npub or hex>GET /api/status/<pubkey> returns {"action":"accept"} for members and {"action":"reject"} otherwise.
GET /api/user/<pubkey> returns membership and invoice status as JSON.
nerostr watches its own payment processing. It counts as broken when the wallet RPC can't be reached, or when the wallet height hasn't moved for 30 minutes (usually its Monero daemon is down or not syncing).
- Nostr DMs. After
ALERT_AFTERseconds of trouble (10 minutes by default), the relay sends an encrypted NIP-17 DM to eachALERT_PUBKEYS(default:ADMIN_PUBKEYS). It sends another DM when payments recover. DMs go to the recipient's DM relays (kind 10050) and are stored on this relay too. They come from the relay's own key: theselfpubkey in NIP-11, also printed at startup. - Heartbeat. Set
HEARTBEAT_URLto a push-monitor URL (healthchecks.io, Uptime Kuma push monitors, …). nerostr requests it everyHEARTBEAT_INTERVALseconds while healthy, so the monitor alerts you when pings stop. That includes the whole server being down, which nothing inside the relay can report. /healthzreturns the same status as JSON, for any HTTP monitor.
Everything lives in ./data:
| Path | What | Back up? |
|---|---|---|
data/wallet/ |
Wallet files and password | Yes. Keep your seed offline as well. |
data/nerostr/nerostr.db |
Members, invoices, bans (SQLite) | Yes. nerostr also writes a daily snapshot to data/nerostr/backups/ (7 kept). |
data/nerostr/events/ |
Events (LMDB) | Optional; stop nerostr first, or copy it with mdb_copy. |
data/nerostr/relay.key |
The relay's own nostr key | Yes, unless you set RELAY_SECRET_KEY. A lost key means alerts come from a new identity. |
If you ever restore the wallet from its seed, set the subaddress lookahead above the number of invoices you've created. Otherwise old subaddresses won't be detected.
git pull
docker compose pull # or: docker compose build
docker compose up -dThe Monero version is pinned in wallet-rpc/Dockerfile, with checksums from the signed hashes.txt.
Upgrade it promptly when a new Monero release is out. The FCMP++ hard fork, in particular, will require one.
v2 replaces the nerostr + strfry + plugin setup with a single service. Members and events carry over, and v1's files are never modified.
v1 is the v0.0.x series; its documentation stays at the v0.0.71 tag.
v2 is a migration, not an image update. Until you migrate, pin the v1 images in your v1 docker-compose.yml:
image: pluja/nerostr:v0.0.71
image: pluja/nerostr-strfry@sha256:1ab3e92e7559783e83eeea4926d87d9331026462dad029030c8fa7e7a5d4a19dThe steps assume your v1 directory is ~/nerostr (with nerostr_data/) and v2 goes to ~/nerostr-v2.
-
Export events while v1 keeps running:
cd ~/nerostr date +%s > export-started docker exec nerostr-strfry-relay /app/strfry export > events.jsonl
-
Prepare v2 next to it, reusing the same wallet:
git clone https://github.com/pluja/nerostr ~/nerostr-v2 && cd ~/nerostr-v2 mkdir -p data/nerostr data/wallet cp ~/nerostr/nerostr_data/wallet/<wallet> ~/nerostr/nerostr_data/wallet/<wallet>.keys data/wallet/ printf '%s' '<MONERO_WALLET_PASSWORD from the v1 .env>' > data/wallet/password && chmod 600 data/wallet/password sudo chown -R 1000:1000 data cp example.env .env
In
.env:- set
PUBLIC_URLtohttps://plus your v1NEROSTR_HOST; - set
MONERO_DAEMON_ADDRESSto your v1MONERO_DAEMON_RPC_HOSTNAME:MONERO_DAEMON_RPC_PORT; - copy
MONERO_WALLET_FILENAME,ADMISSION_AMOUNTandINVOICE_EXPIRE_TIME; - set a new
MONERO_WALLET_RPC_PASSWORD; - keep
API_KEYif you used the v1 API.
- set
-
Import events while v1 is still serving. The import re-verifies every signature and applies the same flood rule as the relay, so the first copy of each repeated note is kept. It is safe to repeat (duplicates are skipped). xmr.usenostr.org's 933k events took about 30 minutes, ending at 392k after dropping a 541k-note bridge loop from July 2024:
docker compose run --rm -v ~/nerostr/events.jsonl:/import/events.jsonl:ro nerostr import /import/events.jsonl -
Stop v1, import what changed meanwhile, and migrate members:
cd ~/nerostr docker exec nerostr-strfry-relay /app/strfry export --since=$(( $(cat export-started) - 600 )) > events-delta.jsonl docker compose down cd ~/nerostr-v2 docker compose run --rm -v ~/nerostr/events-delta.jsonl:/import/events.jsonl:ro nerostr import /import/events.jsonl docker compose run --rm -v ~/nerostr/nerostr_data/nerostr/nerostr-db:/v1db:ro nerostr migrate-v1 /v1db
migrate-v1copies every paid user. If v1 was not shut down cleanly, it recovers a temporary copy and leaves the original alone. -
Start v2 and point your reverse proxy at it (for caddy-docker-proxy, use the override):
docker compose up -d
To roll back, run docker compose down in ~/nerostr-v2 and docker compose up -d in ~/nerostr.
Two v1 leftovers:
- Unpaid v1 invoices are not carried over. Payments to them still reach your wallet, and you can grant those users access with
allowpubkey. - The v1 strfry relay accepted events from members only, so imported events need no further filtering.
You need Go and, for the Dockerfile and workflow audits, Docker or Podman.
make check # everything CI runs: tidy, formatting, lint, tests, vulnerabilities, workflow and Dockerfile checks
make fmt # format Go code (gofmt + goimports)
PUBLIC_URL=http://localhost:8080 DATA_DIR=./data/dev go run .The linters are configured in .golangci.yml and .hadolint.yaml.
Their versions are pinned in the Makefile, which CI also uses, so local and CI results match.
A //nolint comment must name the linter and say why.
The code is small:
internal/relay: khatru setup, write policy and NIP-86;internal/payments: invoices and the payment monitor;internal/web: pages and HTTP API;internal/store: SQLite;internal/wallet: wallet RPC client;internal/flood: the repeated-note rule;internal/alerts: alert DMs and heartbeat.
| Workflow | Runs on | Does |
|---|---|---|
ci |
pushes to main, pull requests |
make check, then builds the images (amd64 and arm64) and smoke-tests the container. |
release |
v* tags |
Runs ci, then publishes the multi-arch image, static Linux binaries with SHA256SUMS, and a GitHub release with generated notes. |
wallet-rpc |
changes to wallet-rpc/, weekly, manually |
Publishes the wallet image, tagged with its Monero version and latest. The weekly run picks up Debian security fixes. |
Images are published to ghcr.io/<owner>/ with the workflow's own token, so no registry secrets are needed.
Every image has an SBOM and a signed build-provenance attestation; binaries are attested too.
Release builds never use the build cache.
One-time setup in the GitHub repository settings:
- Environment
release, which the publishing jobs run in. Allow onlymainand tags matchingv*to deploy to it. - A tag ruleset for
v*, so only maintainers can create, move or delete release tags. - After the first publish, open each package (
nerostr,nerostr-wallet-rpc) under your profile's Packages. Set its visibility to public: new packages on user accounts start out private.
To release:
git tag -s v2.0.0 -m v2.0.0 && git push origin v2.0.0A tag with a suffix, such as v2.0.0-rc.1, becomes a pre-release. It doesn't move latest or the 2 and 2.0 image tags, so it is safe for trying out a release.
To verify a published image or binary:
gh attestation verify oci://ghcr.io/pluja/nerostr:2.0.0 --owner pluja
gh attestation verify nerostr_v2.0.0_linux_amd64.tar.gz --owner pluja| Relay | Paywall | Status and info |
|---|---|---|
| wss://xmr.usenostr.org | xmr.usenostr.org | info |
| wss://nostr.portemonero.com | nostr.portemonero.com | info |
| wss://xmr.ithurtswhenip.ee | xmr.ithurtswhenip.ee | info |
| wss://nostr.xmr.rocks | nostr.xmr.rocks | info |