Nostr relay

A nostr relay written in Rust with support for the entire relay protocol and data persistence using SQLite.

What is Nostr?

Nostr is a straightforward and open protocol for global, decentralized, and censorship-resistant social media. It offers numerous advantages for users and is completely free, requiring no ID or third-party verification to begin connecting with like-minded individuals and expanding your community. While nostr is sometimes confused as just another social media platform, it goes beyond that. Explore the resources provided here to discover its significant potential.

This protocol is based on relays. Relays are servers that can be operated by anyone. By opening a persistent connection with the server, clients (or apps) can push and pull events in real-time.

Relays are the central element of the nostr protocol, responsible for storing events received from clients.

Crucially, relays do not communicate with each other. Only the relays you're connected to will receive and store your events. This is a key feature of nostr, emphasizing the lack of communication between relays. Therefore, you should connect to as many relays as you wish to share your data with.

Clients should always provide users the flexibility to connect to multiple relays. Users can also decide whether they want to read, write, or do both with the relays they're connected to. This means I can choose to connect to a specific relay to access content without necessarily sharing my own events there, or vice versa.

You can obtain more info about nostr on these additional resources:



Install dependencies

  • With user admin, make sure that all necessary software packages are installed

sudo apt install build-essential cmake protobuf-compiler pkg-config libssl-dev

If you want to use the default SQLite database backend, go to the Use the default SQLite database backend extra section to install the additional SQLite dependency packages

Install Rustup + Cargo

  • Check if you already have Rustup installed

rustc --version

Example of expected output:

> rustc 1.71.0 (8ede3aae2 2023-07-12)
  • Also Cargo

cargo -V

Example of expected output:

> cargo 1.71.0 (cfd3bbd8f 2023-06-08)

If you obtain "command not found" output, you need to follow the Rustup + Cargo bonus guide to install it and then come back to continue with the guide

Install PostgreSQL

Skip this step if you want to use the SQLite database, go directly to the next section

  • Check if you already have PostgreSQL installed

psql -V

Example of expected output:

> psql (PostgreSQL) 15.3 (Ubuntu 15.3-1.pgdg22.04+1)

If you obtain "command not found" outputs, you need to follow the PostgreSQL bonus guide to install it and then come back to continue with the guide

Create PostgreSQL database

  • With user admin, create a new database with the postgres user and assign as the owner to the admin user

sudo -u postgres createdb -O admin nostrelay


  • With user admin, go to the temporary folder

cd /tmp
  • Clone the source code directly from the GitHub repository, and then build a release version of the relay and go to the nostr-rs-relay folder

git clone && cd nostr-rs-relay
  • Build a release version of the relay

cargo build --release
Example of expected output ⬇️
    Updating index
  Downloaded pathdiff v0.2.1
  Downloaded num_cpus v1.16.0
  Downloaded indexmap v2.0.0
  Downloaded parking_lot_core v0.9.8
  Downloaded want v0.3.1
  Downloaded pest v2.7.2
  Downloaded percent-encoding v2.3.0
  Downloaded parse_duration v2.1.1
  Downloaded prost-build v0.11.9
  Downloaded clap_lex v0.5.0
  Downloaded autocfg v0.1.8
  Downloaded fastrand v2.0.0
  Downloaded is-terminal v0.4.9
  Downloaded json5 v0.4.1
  Downloaded num v0.2.1
  Downloaded paste v1.0.14
  Downloaded pin-project-internal v1.1.3
  Downloaded num-iter v0.1.43
  Downloaded fallible-streaming-iterator v0.1.9
  Downloaded md-5 v0.10.5
  Downloaded linked-hash-map v0.5.6
  Downloaded number_prefix v0.4.0
  Downloaded itoa v1.0.9
  Downloaded openssl-sys v0.9.91
  Downloaded async-lock v2.7.0
  Downloaded pest_derive v2.7.2
  Downloaded async-channel v1.9.0
  Downloaded tokio-io-timeout v1.2.0
  Downloaded async-global-executor v2.3.1
  Downloaded sync_wrapper v0.1.2
  Downloaded matchers v0.1.0
  Downloaded no-std-compat v0.4.1
  Downloaded block-padding v0.3.3
  Downloaded pest_generator v2.7.2
  Downloaded atomic-waker v1.1.1
  Downloaded pin-project-lite v0.2.12

If the prompt shows you this error:

error: rustup could not choose a version of cargo to run, because one wasn't specified explicitly, and no default is configured. help: run 'rustup default stable' to download the latest stable release of Rust and set it as your default toolchain.

You need to type rustup default stable and wait for the process to finish, then try again the command before

  • Install it

sudo install -m 0755 -o root -g root -t /usr/local/bin /tmp/nostr-rs-relay/target/release/nostr-rs-relay
  • Check the correct installation

nostr-rs-relay -V

Example of expected output:

> nostr-rs-relay 0.8.9

If you come to update this is the final step, continue with the indications of the Upgrade section

Create the nostr user

  • Create the user nostr with this command

sudo adduser --gecos "" --disabled-password nostr

Expected output:

Adding user `nostr' ...
Adding new group `nostr' (1007) ...
Adding new user `nostr' (1007) with group `nostr' ...
Creating home directory `/home/nostr' ...
Copying files from `/etc/skel' ...
  • Change to the home nostr user folder

sudo su - nostr
  • (Optional) If you want to use the MiniBolt favicon.ico file, download it by entering this command, if not, download your own or skip this step to not provide any

  • Create the rs-relay folder

mkdir rs-relay
  • Exit to the admin user



  • Copy-paste the configuration file template to the before-created folder

sudo cp /tmp/nostr-rs-relay/config.toml /home/nostr/rs-relay/
  • Assign the owner of the file to the nostr user

sudo chown nostr:nostr /home/nostr/rs-relay/config.toml
  • Delete the nostr-rs-relay folder to be ready for the next update

sudo rm -r /tmp/nostr-rs-relay
  • Edit the config file, uncomment, and replace the needed information on the next parameters. Save and exit

sudo nano /home/nostr/rs-relay/config.toml

Pay attention to not include the next lines:

engine = "postgres"

connection = "postgresql://admin:admin@localhost:5432/nostrelay"

Include the uncomment, and replace the next line:

data_directory = "/data/nostr/rs-relay/db"

If you want to use the default SQLite database backend. More details and additional steps on the exclusive extra section

Customize this with your own info (*):

(*) Click on parameter to get an example/explanation

relay_url = "<yourelayurl>"

name = "<nametotherelay>"

description = "<descriptionrelay>"

pubkey = "<yournostrhexpubkey>"

contact = "<yourcontact>"

relay_icon = "<yourelayiconURL>"

If you don't have pubkey generated yet, you can follow the Create your nostr key pair section and then continue with this.

You can use this tool to convert your "npub" pubkey to hexadecimal format

Required same as next (*):

(*) click on the parameter to get action to do (<Edit> or <Uncomment>)

favicon = "favicon.ico"

engine = "postgres"

connection = "postgresql://admin:admin@localhost:5432/nostrelay"

address = ""

port =

remote_ip_header = "cf-connecting-ip"

If you want, use the same favicon.ico file downloaded before (the relay's icon of MiniBolt) and the value relay_icon parameter (URL), or replace it with your own, downloading it instead

Create systemd service

The system needs to run the nostr relay daemon automatically in the background, even when nobody is logged in. We use systemd, a daemon that controls the startup process using configuration files.

  • As user admin, create the service file

sudo nano /etc/systemd/system/nostr-relay.service
  • Paste the following configuration. Save and exit

# MiniBolt: systemd unit for nostr relay
# /etc/systemd/system/nostr-relay.service

Description=Nostr relay postgresql.service postgresql.service

ExecStart=/usr/local/bin/nostr-rs-relay -c /home/nostr/rs-relay/config.toml


# Process management

  • Enable autoboot (optional)

sudo systemctl enable nostr-relay
  • Prepare “nostr-relay” monitoring by the systemd journal and check the logging output. You can exit monitoring at any time with Ctrl-C

journalctl -fu nostr-relay


To keep an eye on the software movements, start your SSH program (eg. PuTTY) a second time, connect to the MiniBolt node, and log in as admin

  • Start the nostr relay

sudo systemctl start nostr-relay
Example of expected output on the first terminal with journalctl -fu nostr-relay ⬇️
Jun 07 10:49:45 minibolt systemd[1]: Started Nostr relay.
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.130712Z  INFO nostr_rs_relay: Starting up from main
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.150378Z  INFO nostr_rs_relay::server: listening on:
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.302830Z  INFO sqlx::postgres::notice: relation "migrations" already exists, skipping
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.337047Z  INFO nostr_rs_relay::db: Postgres migration completed, at v5
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.337902Z  INFO nostr_rs_relay::server: db writer created
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.337945Z  INFO nostr_rs_relay::server: control message listener started
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.338012Z  INFO nostr_rs_relay::server: reading favicon...
  • Ensure the service is working and listening at the default 8880 port

sudo ss -tulpn | grep LISTEN | grep nostr-rs-relay

Expected output:

> tcp   LISTEN 0   128*  users:(("nostr-rs-relay",pid=138820,fd=24))

Cloudflare tunnel

Follow the Cloudflare Tunnel bonus guide, when you arrive at the Configuration file section, add the next # Nostr relay lines to ingress the related ingress rule

nano /home/admin/.cloudflared/config.yml
# MiniBolt: cloudflared configuration
# /home/admin/.cloudflared/config.yml

tunnel: <UUID>
credentials-file: /home/admin/.cloudflared/<UUID>.json


# Nostr relay
  - hostname: relay.
    service: ws://localhost:8880

  - service: http_status:404

Remember to keep - service: http_status:404 line at the end of the file

  • Restart the Cloudflared service

sudo systemctl restart cloudflared
  • Check the Cloudflared logs to ensure all is still OK

journalctl -fu cloudflared

Check relay connection

-> 3 different methods ⬇️

Expected output:

Extras (optional)

Use the default SQLite database backend

  • With user admin, install the next additional dependencies

sudo apt install sqlite3 libsqlite3-dev
  • Create the rs-relay and db folder

mkdir -p /data/nostr/rs-relay/db
  • Assign as the owner to the nostr user

sudo chown -R nostr:nostr /data/nostr
  • Edit the config file

sudo nano /data/nostr/rs-relay/config.toml
  • Uncomment, and replace the needed information on the next parameters. Save and exit

data_directory = "/data/nostr/rs-relay/db"

Ignore the next lines related to the PostgreSQL (not uncomment or edit):

engine = "postgres"

connection = "postgresql://admin:admin@localhost:5432/nostrelay"
  • Delete postgres.service of the systemd service lines

Continue with the guide, the rest of the steps are the same as PostgreSQL use

Create your nostr key pair

  • Download and install the Alby Browser extension:

  • After installation, the browser automatically redirects you to choose the password to unlock Alby. Click on the [Next] button

Select a strong password for the Alby extension (this password is for encrypting your future Nostr private key and possible funds of the integrated LN wallet)

  • Select [Connect with Alby]

  • Login with your existing account or create a new one

  • If you selected to create a new one, you need to provide a valid email

  • If you selected to log in, you need to provide the email and password or select a one-time login code method that you chose

  • Click on [Start buzzin' with Alby]. Pin the Alby extension to the browser toolbar, if you want

  • On the Alby dashboard, select the [Nostr section]

  • Select to create a new one nostr key pairs or import an existing one if you have

  • If you selected to create a new one, remember to backup the seed shown on the screen, check the verification box, and click on the [Save Master Key] box

You will see the nostr public & private keys in the property section:

Click on the [Nostr Settings] box to obtain your private key and backup on your password manager app, you will need it for mobile clients (e.g. Amethyst) where you will need to enter manually. Example:

  • If you selected Import a Nostr account, you can import using the Nostr private key or Recovery phrase

  • If you selected the Nostr private key, fill in the "Nostr Private key" box with your private key, it will derivate you the "Nostr Public Key", check if correct

If you see this banner when you enter the "Nostr Settings" section, this means that you should backup carefully the private key, because the existing seeds that you have are not compatible with Alby only the private key

  • If you selected the Recovery phrase, fill in the 12-24 words and click on the [Import Master Key] box

You will see the Nostr Public key in the property section, check if correct:

Click on the [Nostr Settings] box to obtain your private key if you don't have yet:

Now, you can use Alby to log in to compatible web clients using NIP-07 [Login from extension]

If you prefer to generate your key pair, you can mine them using the Rana tool and the Minibolt node.

Be careful when doing this, as it will use all the available resources of the machine and could render other important applications you are running unusable. Gracefully shutdown them before starting this process

Broadcast the past events to your new relay (optional)

If you want all your past events to be accessible through your new relay, you can back them up by following these instructions:

  • Go to website, log in [Load My Profile], and click on [Relays]

  • Add your new Nostr relay [wss://] address to the list of preferred relays in your profile (in the empty box below), select the read+write option, and click the [Update] button.

    You can take the opportunity to add more preferred relays to your profile to also push events to them, selected from this list, or use Nosy to find the top relays of those who follow you or you follow and try to connect to them and don't forget any events of your contact network

  • Go to webpage and log in [Get from extension] (Alby), or manually enter the [npub...] of your Nostr profile

  • Click the [Backup & Broadcast] button...

Please wait patiently until all processes are finished. This might take some time, depending on the number of events you've published on Nostr with that pubkey meaning the interactions you've had on Nostr.

Optionally, you can save a copy of all your events locally as you'll have the download option.

Nostr clients

Coracle is a web client for the Nostr protocol focused on pushing the boundaries of what's unique about Nostr, including relay selection and management, web-of-trust based moderation and content recommendations, and privacy protection.

Web | GitHub

A Nostr-based application to create, manage, and discover link lists, show notes, and other stuff.

Web | GitHub does NOSTR things... documents, links, graphs, maps, and more... is a portal to your decentralized data.


A free, open source, and decentralized password manager, powered by NOSTR.

Chrome-based extension | GitHub


  • With user admin, stop nostr-rs-relay service

sudo systemctl stop nostr-relay
  • Follow the complete Installation section

  • Replace the config.toml file with the new one of the new version (if needed)

This step is only necessary if you see changes on the config file template from your current version until the current release (not common), you can display this on this history link. If there are no changes, jump directly to the next "Start nostr-rs-relay service again" >sudo systemctl start nostr-relay

  • Backup the config.toml file to keep a copy of your old configuration

sudo cp /data/nostr/rs-relay/config.toml /data/nostr/rs-relay/config.toml.backup
  • Assign the owner of the backup file to the nostr user

sudo chown nostr:nostr /data/nostr/rs-relay/config.toml.backup
  • Replace the new config.toml file of the new release

sudo cp /tmp/nostr-rs-relay/config.toml /data/nostr/rs-relay/
  • Edit the config file and replace it with the same old information as the file you had. Save and exit

sudo nano /data/nostr/rs-relay/config.toml
  • Start nostr-rs-relay service again

sudo systemctl start nostr-relay
  • Delete the nostr-rs-relay folder to be ready for the next update

sudo rm -r /tmp/nostr-rs-relay


Uninstall service & user

  • Ensure you are logged in with the user admin, stop nostr-relay service

sudo systemctl stop nostr-relay
  • Delete nostr-relay service

sudo rm /etc/systemd/system/nostr-relay.service
  • Delete the nostr user. Don't worry about userdel: nostr mail spool (/var/mail/nym) not found output, the uninstall has been successful

sudo userdel -rf nostr

Expected output:

> userdel: nostr mail spool (/var/mail/nostr) not found
  • Delete the nostr relay data folder

sudo rm -r /data/nostr/relay

Uninstall the nostr relay of the Cloudflare tunnel

  • Staying with user admin, edit config.yml

nano /home/admin/.cloudflared/config.yml
  • Comment or delete the nostr relay associated ingress rule. Save and exit

# MiniBolt: cloudflared configuration
# /home/admin/.cloudflared/config.yml

tunnel: <UUID>
credentials-file: /home/admin/.cloudflared/<UUID>.json


# Nostr relay
#  - hostname: relay.<>
#    service: ws://localhost:8880

  - service: http_status:404
  • Restart the Cloudflare tunnel to apply the changes

sudo systemctl restart cloudflared

Uninstall binaries

  • Staying with user admin, delete the nostr-rs-relay binary of the system

sudo rm /usr/local/bin/nostr-rs-relay

Port reference




Default port

Last updated