Node Setup

Step 1: Prepare the Server

SSH into your Supernode server (not the validator) and install the required packages:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget jq ufw lz4 tar golang-go

Never run a Supernode and validator on the same server. They must be on separate machines. The setup script will refuse to run if it detects a validator service on the same host.

Step 2: Configure Firewall

Open the ports required by sn-manager:

sudo ufw allow 22/tcp comment "SSH"
sudo ufw allow 4444/tcp comment "SuperNode gRPC"
sudo ufw allow 4445/tcp comment "SuperNode P2P"
sudo ufw allow 8002/tcp comment "SuperNode REST"
sudo ufw --force enable
sudo ufw status

You should see all four ports listed as ALLOW.

Step 3: Choose a Lumera gRPC Endpoint

The Supernode needs a gRPC endpoint to query the chain and broadcast its on-chain messages. You have two options.

Option 1: Use a public testnet gRPC endpoint (recommended)

The simplest and most common setup is to point sn-manager at one of the community-run public testnet-2 gRPC endpoints. You do not need to touch your validator, open any ports on it, or edit app.toml. Pick any of the endpoints listed on the Community Endpoints page, for example:

https://lumera-testnet-grpc.linknode.org (Astrostake)
lumera-testnet-grpc.stakerhouse.com:443 (StakerHouse)
https://grpc-t.lumera.nodestake.org/ (Nodestake)

Note the endpoint you picked, you will pass it as --lumera-grpc in Step 5.

Option 2: Self-host your validator's gRPC (advanced)

If you prefer to route Supernode traffic through your own validator instead of a third-party endpoint, you can expose the validator's built-in gRPC port. This gives you sovereignty and lower latency, but increases the validator's attack surface and requires you to maintain firewall rules in two places.

Only follow this section if you have a specific reason to avoid public endpoints.

Expose validator gRPC on port 9090

Bind gRPC to all interfaces. SSH into your validator server and run:

# Check current gRPC config
grep -A 5 "^\[grpc\]" ~/.lumera/config/app.toml
 
# Change localhost to 0.0.0.0
sed -i 's|address = "localhost:9090"|address = "0.0.0.0:9090"|' ~/.lumera/config/app.toml
 
# Restart the validator
sudo systemctl restart lumera

Restrict access to the Supernode IP. Do not expose port 9090 publicly:

sudo ufw allow from <SUPERNODE_IP> to any port 9090 proto tcp comment "SuperNode gRPC"

Replace <SUPERNODE_IP> with your Supernode server's public IP address. You must also open the port in your cloud provider's firewall (Azure NSG, AWS Security Group, GCP VPC firewall, DigitalOcean Cloud Firewall) — ufw alone is not enough.

Verify the listener. On the validator:

sudo ss -tlnp | grep 9090

You should see *:9090 or 0.0.0.0:9090. A line containing 127.0.0.1:9090 means the app.toml edit did not apply — re-check the file and restart lumera again.

Verify reachability from the Supernode:

curl -v telnet://<VALIDATOR_IP>:9090 --max-time 3 2>&1 | head -5

You should see Connected to <VALIDATOR_IP> port 9090. A timeout usually means the cloud firewall is blocking — ufw is not the only layer.

You will pass <VALIDATOR_IP>:9090 as --lumera-grpc in Step 5.

Step 4: Install sn-manager

Download and install the latest sn-manager release:

curl -L https://github.com/LumeraProtocol/supernode/releases/latest/download/supernode-linux-amd64.tar.gz | tar -xz
 
mkdir -p ~/.sn-manager/bin
install -D -m 0755 sn-manager ~/.sn-manager/bin/sn-manager

Add sn-manager to your PATH:

echo 'export PATH="$HOME/.sn-manager/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
 
sn-manager version

Step 5: Initialize the Supernode

Set a passphrase for the keyring and initialize:

export SUPERNODE_PASSPHRASE="your-secure-passphrase"
 
sn-manager init -y \
  --auto-upgrade \
  --keyring-backend file \
  --keyring-passphrase-env SUPERNODE_PASSPHRASE \
  --key-name supernode \
  --supernode-addr 0.0.0.0 \
  --supernode-port 4444 \
  --lumera-grpc https://lumera-testnet-grpc.linknode.org \
  --chain-id lumera-testnet-2

Use whichever public testnet gRPC endpoint you chose in Step 3. If you picked Option 2 (self-host) instead, replace the URL with <VALIDATOR_IP>:9090.

**--keyring-passphrase-env takes the name of an environment variable, not the passphrase itself.

The passphrase must be at least 8 characters. It protects the Supernode wallet key stored in the file-based keyring. Write it down now — you will need to enter the exact same value in the systemd service file in Step 6.

Save the mnemonic that is displayed immediately. This is the only backup of your Supernode wallet key. If you lose it, you lose access to the Supernode account and any delegated funds.

The output includes the Supernode account address (SN_ACCOUNT starts with lumera1...). Note this address: you will need it for funding, delegation, and registration.

Recovering an existing key

If you have a mnemonic from a previous installation, add the --recover and --mnemonic flags:

sn-manager init -y \
  --auto-upgrade \
  --keyring-backend file \
  --keyring-passphrase-env SUPERNODE_PASSPHRASE \
  --key-name supernode \
  --supernode-addr 0.0.0.0 \
  --supernode-port 4444 \
  --lumera-grpc https://lumera-testnet-grpc.linknode.org \
  --chain-id lumera-testnet-2 \
  --recover --mnemonic "your 24 word mnemonic phrase here"

The --lumera-grpc must point to a testnet gRPC endpoint. Use one of the public endpoints from Step 3, or <VALIDATOR_IP>:9090 if you self-hosted.

Step 6: Create the Systemd Service

sudo tee /etc/systemd/system/sn-manager.service > /dev/null <<EOF
[Unit]
Description=Lumera SuperNode Manager
After=network-online.target
Wants=network-online.target
 
[Service]
User=$USER
Environment=HOME=$HOME
Environment=SUPERNODE_PASSPHRASE=your-secure-passphrase
WorkingDirectory=$HOME
ExecStart=$HOME/.sn-manager/bin/sn-manager start
Restart=on-failure
RestartSec=10
LimitNOFILE=65536
 
[Install]
WantedBy=multi-user.target
EOF

Replace your-secure-passphrase with the passphrase you chose in Step 5.

The SUPERNODE_PASSPHRASE in this service file must be exactly the passphrase you used in Step 5 — character for character, with no typos or trailing whitespace. Any mismatch causes the SuperNode process to loop on incorrect passphrase at startup and fail to load the keyring. This is the single most common post-install failure, so double-check the value before starting the service.

Secure the service file (it contains your passphrase) and enable it:

sudo chmod 600 /etc/systemd/system/sn-manager.service
sudo systemctl daemon-reload
sudo systemctl enable sn-manager

The systemd service file stores your keyring passphrase in plaintext. It is protected by chmod 600 (root-only read), but be aware of this when managing your server.

Step 7: Start the Supernode

sudo systemctl start sn-manager

Check the service status

sudo systemctl status sn-manager

Watch the logs

sudo journalctl -fu sn-manager

Run a health check

sn-manager status
sn-manager check

The health check may not pass until the Supernode is registered on-chain (next page). This is expected.

Step 8: Install lumerad CLI (Required for Registration)

The registration flow on the next page requires signing a staking delegate transaction from the Supernode key. Because that key lives in ~/.supernode/keys/ on this host, the delegation must be signed on this same machine.

You only need the lumerad CLI binary here, not a full chain node. Do not run lumerad init or lumerad start on this host — doing so would spin up a second, unrelated chain node in ~/.lumera/ that has nothing to do with your Supernode. You are only installing the binary so you can run lumerad tx and lumerad keys subcommands against the Supernode keyring.

Build lumerad from source

Clone the Lumera repository, check out the latest stable tag, and build the binary into ~/go/bin/:

git clone https://github.com/LumeraProtocol/lumera.git ~/lumera-src
cd ~/lumera-src
git checkout v1.11.1   # replace with the current stable tag if newer
go build -o ~/go/bin/lumerad ./cmd/lumera

Add lumerad to your PATH

By default, ~/go/bin is not on your shell PATH, so lumerad will return command not found even after a successful build. Add it:

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
lumerad version

You should see a version string printed. Your Supernode host is now ready to sign the delegation transaction in Register Supernode, Step 2.

Every lumerad command you run on the Supernode host must include --keyring-backend file and --keyring-dir ~/.supernode/keys, because the Supernode key lives at ~/.supernode/keys/ and uses the file keyring backend, neither of which are lumerad's defaults. For transaction commands (lumerad tx ...), you also need --node <RPC_ENDPOINT> to point the CLI at a CometBFT RPC for testnet-2, since the Supernode host has no local chain node. Use a public testnet endpoint such as https://lumera-testnet-rpc.polkachu.com/, or tcp://<VALIDATOR_IP>:26657 if you prefer to broadcast through your own validator (which requires opening port 26657).

Quickly verify the setup by printing the SN key's address — it should match the one you noted during Step 5:

lumerad keys show supernode -a --keyring-backend file --keyring-dir ~/.supernode/keys

You will be prompted for the keyring passphrase (the one you set in Step 5). A successful output is a single lumera1... line.