Skip to main content

Installing a Node

Ensure the requirements listed in the following sections are met before you start setting up the node on the network, either on Mainnet or Testnet.

Network Requirements

The following ports are used by the node:

  • 35000 (required to be externally visible)
  • 7777 RPC endpoint for interaction with JSON-RPC API
  • 8888 REST endpoint for status and metrics (having this accessible allows your node to be part of network status)
  • 9999 SSE endpoint for event stream

Of these 35000 is the only port required to be open for your node to function, however, opening 8888 will allow others to know general network health. For more details, see the additional information on Node Endpoints.

Operating System Requirements

The recommended OS version is Ubuntu 20.04.

Required Number of Open Files

Before beginning, update the maximum open files limit for your system. Specifically, update the node's /etc/security/limits.conf file as described here, to ensure proper node operation.

Required Clean Up

If you were running a previous node on this box, this will clean up state. If packages are not installed, the apt remove may give errors, but this is not a problem.

sudo systemctl stop casper-node-launcher.service
sudo apt remove -y casper-client
sudo apt remove -y casper-node
sudo apt remove -y casper-node-launcher
sudo rm /etc/casper/casper-node-launcher-state.toml
sudo rm -rf /etc/casper/1_*
sudo rm -rf /var/lib/casper/*

Required Packages

The following commands will set up the Casper Labs repository for packages:

echo "deb" bionic main | sudo tee -a /etc/apt/sources.list.d/casper.list
curl -O
sudo apt-key add casper-repo-pubkey.asc
sudo apt update

Required Tools

sudo apt install -y casper-client casper-node-launcher jq

Enable Bash Auto-Completion for casper-client (Optional)

sudo casper-client generate-completion

It defaults to bash but can be changed with the --shell argument:

--shell <STRING>    The type of shell to generate the completion script for [default: bash]  [possible values:
zsh, bash, fish, powershell, elvish]

sudo casper-client generate-completion --shell powershell

You need to source the new auto completion script or log out and log in again to activate it for the current shell:

source /usr/share/bash-completion/completions/casper-client

Now you can use casper-client and press the tab key to get auto completion for your commands.

Installing All Protocols

On Mainnet, run:

sudo -u casper /etc/casper/ stage_protocols casper.conf

On Testnet, run:

sudo -u casper /etc/casper/ stage_protocols casper-test.conf

Validator Keys

If you do not have keys yet, you can create them using the following command:

sudo -u casper casper-client keygen /etc/casper/validator_keys

For more details, see the Node Setup page.

Getting a Trusted Hash

To get a trusted hash, use the command below. Replace the node address with an address from a node on the network of your choice.

sudo sed -i "/trusted_hash =/c\trusted_hash = '$(casper-client get-block --node-address -b 20 | jq -r .result.block.hash | tr -d '\n')'" /etc/casper/1_0_0/config.toml

You can find active peers at

Starting the Node

Start the node using the following commands:

sudo /etc/casper/ rotate_logs
sudo /etc/casper/ start

Monitoring the Synchronization Process

The following command will display the node synchronization details:

/etc/casper/ watch

When you first run the watch command, you may see the message RPC: Not Ready. Once the node is synchronized, the status will change to RPC: Ready and a similar output:

Last Block: 630151 (Era: 4153)
Peer Count: 297
Uptime: 4days 6h 40m 18s 553ms
Build: 1.4.5-a7f6a648d-casper-mainnet
Key: 0147b4cae09d64ab6acd02dd0868722be9a9bcc355c2fdff7c2c244cbfcd30f158
Next Upgrade: None

RPC: Ready

● casper-node-launcher.service - Casper Node Launcher
Loaded: loaded (/lib/systemd/system/casper-node-launcher.service; enabled; vendor preset: enabled)
Active: active (running) since Wed 2022-03-16 21:08:50 UTC; 4 days ago
Main PID: 2934 (casper-node-lau)
Tasks: 12 (limit: 4915)
CGroup: /system.slice/casper-node-launcher.service
├─ 2934 /usr/bin/casper-node-launcher
└─16842 /var/lib/casper/bin/1_4_5/casper-node validator /etc/casper/1_4_5/config.toml

If the node is not showing active (running) status, it is either stopped or in the process of restarting.

Monitoring the Running Node

The community has created a few tools to monitor your node once it is running, such as: