Pick your setup
There are a few ways to run a Dassie node. They run the same code; what differs is where it runs and how others reach it. This page helps you choose.
On this page
Side by side
| Setup | You need | You get | Others reach you |
|---|---|---|---|
| A server with a domain name | Linux with systemd, a public IP address, a domain name that points to it, and open ports | A core node once its uplinks promote it: it forwards payments for others, swaps assets with its peers, and updates itself every day |
At your domain name, for example $pay.example.com,
whenever the server runs
|
| A NixOS server | The same as above, on NixOS, with flakes | A core node from the release's signed binary, under its own systemd units. Nix updates it, not Dassie. | At your domain name |
| The desktop app | Linux on x86-64, with Nix. No server, no domain, no open ports. | A periphery node in a window, with the wallet in it and a tray icon |
At $<node ID>.dassiepay.net, through
Dassie's front door, while the app runs
|
| A server without a public IP | Linux with systemd, and a way out to the internet. No domain name. | A periphery node that runs all the time, at home or behind a firewall |
At $<node ID>.dassiepay.net, through
Dassie's front door
|
If you are not sure, start with a server with a domain name. It is the setup Dassie has run on the longest, and the Quick Start takes you through it in a few commands.
Core and periphery
A node with a domain name is a core node. Other nodes dial it, it forwards their payments and earns fees for that, and nodes without a public address connect to it as their uplink. It needs a public IP address and these ports open to the world:
- TCP 80, for the certificate from Let's Encrypt;
- TCP 443, for the wallet and Open Payments;
- UDP 443, where nodes talk to each other over QUIC. The node does not start while another program holds it;
- UDP 7768, where anyone may ask for the node's snapshot: the quotes it swaps at, signed. Without it the node still runs, and its peers still get its snapshot.
A node without a domain name is a periphery node. It needs no public address and no open port: it connects out to a few core nodes, which give it an address beneath their own, and it pays and gets paid through them. It forwards nothing for others. Apps and other wallets reach it through a relay that it keeps a connection to, so it is reachable only while it runs. Where UDP is blocked, it reaches core nodes over QUIC inside a WebSocket on their HTTPS port instead, through the network's HTTP proxy if it sets one. Only a node without a domain name does that: a core node needs UDP.
Core and periphery explains both in more depth.
Every node knows the testnet's five bootstrap nodes from the start, so a new periphery node finds core nodes to connect to on its own.
It knows its relay from the start too. Unless you choose another, a
node without a domain name keeps a connection to Dassie's front door
at relay.dassiepay.net, so apps and other wallets reach
it at its default name, $<node ID>.dassiepay.net,
with nothing to set. That has a cost: the front door is a machine
the project runs, so it learns when your node is online, and it
reads the Open Payments requests it passes on. You can name another
relay, or keep none, in DASSIE_RELAY.
The relay shows how.
A node with a domain name keeps no relay unless you name one.
Choosing the relay while you set up in the wallet is not there yet, nor are nodes that start in the periphery and become core once they earn it. Setting up in the wallet, becoming core
The desktop app is always periphery
The desktop app runs your node inside the app, on the computer you
use every day, and shows the wallet in its window. Its wallet listens
only on your own machine, and it has no listener a certificate
authority could reach. So it stays a periphery node, even if you
give it a domain name with dassie init. With a domain
name, though, it keeps no default relay, since it then answers only
under that name.
It keeps running in the tray when you close its window, and once installed it starts when you log in, because your node is reachable only while it runs. Install the desktop app shows how to get it.
The desktop app runs on Linux, built with Nix. Packages for other Linux distributions, macOS and Windows are not there yet. What's next
When headless setup fits
Usually you finish setting up a node in your browser: you open its setup URL, and the browser makes your recovery phrase and hands the node only its key. The phrase never leaves your browser.
Some nodes have nobody to open a browser for them, such as a market
maker's node, or a node you set up from a script. For those,
dassie setup reads the phrase from a file on the node's
own server, sets the node up and adds the settlement schemes you
name. On the testnet it also joins the testnet's XRP hub, unless
--hub names other hubs, or none. It is
safe to run again at every start. The trade-off is that your
phrase now lives on the server, so whoever can read that file
controls the node and its money.
Headless setup works with any of the server setups above. Headless setup shows the steps.
