Skip to content
cameriPublic

About

Own a relay for social network nobody can switch off

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

838 stars

Watchers

23 watching

Forks

Latest commit

 

History

1,063 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

nostream logo

GitHub release GitHub issues GitHub stars GitHub top language GitHub forks GitHub license Coverage Status Build status Greptile: The War on Bugs

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.

Deploy on Railway

Documentation

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

Features

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_at Limits

  • 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_mips advertised in the NIP-11 relay information document

Requirements

Standalone setup

  • PostgreSQL 14.0
  • Redis
  • Node v24
  • Typescript

Docker setups

  • Docker v20.10
  • Docker Compose v2.10

Local Docker setup

  • 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.

Quick Start (Docker Compose)

For full command reference and interactive mode documentation, see CLI.md. Non-interactive CLI usage conventions:

  • exit 0 on success
  • exit 1 on runtime/validation errors
  • exit 2 on 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.

Importing events

Import .jsonl, .json and compressed backups with nostream import. The full reference, including batch sizes and progress output, is in Operations.

NIP-43 invite codes

Mint a code with nostream invite create, or let users request one by setting nip43.allowInviteRequests. See CLI.md and Configuration.

Running from source instead

The standalone path needs PostgreSQL 14, Redis and Node 24. For the full walkthrough, see the development quick start in CONTRIBUTING.md.

Configuration

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.

Dev Channel

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.

Author

I'm Cameri on most social networks. You can find me on Nostr by npub1qqqqqqyz0la2jjl752yv8h7wgs3v098mh9nztd4nr6gynaef6uqqt0n47m.

Contributors (A-Z)

  • 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

License

This project is MIT licensed.

Star History

Star History Chart

About

Own a relay for social network nobody can switch off

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

838 stars

Watchers

23 watching

Forks

Releases

Packages

Used by

Contributors

Languages