This is a nostr relay, written in Typescript. Documentation, features and guides live on the project website: nostream.dev.
This implementation is production-ready. See below for supported features.
The project master repository is available on GitHub.
Start with the guide for what you want to do; the README stays short on purpose.
| Guide | Covers |
|---|---|
| Production setup | Host preparation, Docker Compose, TLS reverse proxy, verification |
| Deployment runbook | Releasing images, zero-downtime updates, health checks |
| Configuration | Every environment variable and setting |
| CLI | nostream commands, exit codes, config commands, development helpers |
| Payments | Charging an admission fee with ZEBEDEE, Nodeless, OpenNode, LNbits, LNURL or NWC |
| Operations | Backups, maintenance, query benchmarking, systemd, troubleshooting |
| Peering | Configuring peers, authenticating, syncing their events |
| Redis | Why the relay needs Redis, and how to configure it |
| Contributing | Development setup, tests, load and performance testing |
| Security policy | Reporting a vulnerability |
| Changelog | Released changes |
NIPs and MIPs with a relay-specific implementation are listed here.
-
NIP-01: Basic protocol flow description
-
NIP-02: Contact list and petnames
-
NIP-03: OpenTimestamps Attestations for Events
-
NIP-04: Encrypted Direct Message
-
NIP-05: Mapping Nostr keys to DNS-based internet identifiers
-
NIP-09: Event deletion
-
NIP-11: Relay information document
-
NIP-12: Generic tag queries
-
NIP-13: Proof of Work
-
NIP-14: Subject tag in text events
-
NIP-15: End of Stored Events Notice
-
NIP-16: Event Treatment
-
NIP-20: Command Results
-
NIP-22: Event
created_atLimits -
NIP-25: Reactions
-
NIP-26: Delegated Event Signing (removed upstream; not implemented)
-
NIP-28: Public Chat
-
NIP-33: Parameterized Replaceable Events
-
NIP-40: Expiration Timestamp
-
NIP-42: Authentication of clients to relays
-
NIP-43: Invite codes
-
NIP-44: Encrypted Payloads (Versioned)
-
NIP-45: Event Counts
-
NIP-50: Search capability
-
NIP-62: Request to Vanish
-
NIP-65: Relay List Metadata
-
NIP-77: Negentropy Synchronization
-
Marmot Protocol MIPs 00–03: E2EE group messaging over Nostr — kinds 443, 444, 445, 10051 and 30443, with
supported_mipsadvertised in the NIP-11 relay information document
- PostgreSQL 14.0
- Redis
- Node v24
- Typescript
- Docker v20.10
- Docker Compose v2.10
- Docker Desktop v4.2.0 or newer
- mkcert
WARNING: Docker distributions from Snap, Brew or Debian repositories are NOT SUPPORTED and will result in errors. Install Docker from their official guide ONLY.
For full command reference and interactive mode documentation, see CLI.md. Non-interactive CLI usage conventions:
- exit
0on success - exit
1on runtime/validation errors - exit
2on usage errors (invalid command/options)
Optional global installation from a source checkout:
pnpm add -g .
nostream --help
Install Docker following the official guide. You may have to uninstall Docker if you installed it using a different guide.
Clone repository and enter directory:
git clone git@github.com:Cameri/nostream.git
cd nostream
Generate a secret with: openssl rand -hex 128
Copy the output and paste it into an .env file:
SECRET=aaabbbccc...dddeeefff
# Secret shortened for brevity
Start:
nostream start
or
nostream start --tor
or
nostream start --i2p
or
RELAY_DOMAIN=relay.example.com CERTBOT_EMAIL=you@example.com nostream start --nginx
Stop the server with:
nostream stop
Print the Tor hostname:
nostream info --tor-hostname
Print I2P hostname(s):
nostream info --i2p-hostname
The old shell wrapper scripts are no longer shipped in scripts/. CLI.md
lists the nostream command each one became.
Import .jsonl, .json and compressed backups with nostream import. The
full reference, including batch sizes and progress output, is in
Operations.
Mint a code with nostream invite create, or let users request one by setting
nip43.allowInviteRequests. See CLI.md and
Configuration.
The standalone path needs PostgreSQL 14, Redis and Node 24. For the full walkthrough, see the development quick start in CONTRIBUTING.md.
You can change the default folder by setting the NOSTR_CONFIG_DIR environment variable to a different path.
Run nostream using one of the quick-start guides at least once and nostream/.nostr/settings.yaml will be created.
Any changes made to the settings file will be read on the next start.
Default settings can be found under resources/default-settings.yaml. Feel free to copy it to nostream/.nostr/settings.yaml if you would like to have a settings file before running the relay first.
See CONFIGURATION.md for a detailed explanation of each environment variable and setting.
For development discussions, please use the Nostr Typescript Relay Dev Group.
For discussions about the protocol, please feel free to use the Nostr Telegram Group.
I'm Cameri on most social networks. You can find me on Nostr by npub1qqqqqqyz0la2jjl752yv8h7wgs3v098mh9nztd4nr6gynaef6uqqt0n47m.
- Abhay
- Abhinav Rathee
- André Neves
- Anshuman
- Anton Livaja
- archief2910
- Chetan Reddy Kodidela
- Divyanshu Kumar
- Juan Angel
- Kanishka
- Kartik
- Kevin Smith
- Khadar Vali
- Khushal
- Kushagra Kinra
- Mahmoud Khedr
- Mohit Davar
- Priyanshu Bharti
- Radosvet Petrov
- Sagar
- Saniddhya Dubey
- Saransh Sharma
- Semisol
- swissrouting
- Tharupahan Jayawardana
- Vikash Siwach
- XD22
- Yash Agarwal
This project is MIT licensed.
