Skip to main content

Running a Node

System Requirements

Operating SystemLinux or MacOS
Number of CPU cores4


30303TCPexecution syncingport must be open
30303UDPexecution discoveryport must be open
13000TCPconsensus syncingport must be open
12000UDPconsensus discoveryport must be open

Network Start

After the Genesis Deposit Contract was frozen on the 9th of May (read the article), LUKSO mainnet started as a PoS Blockchain on the 23rd of May 2023. The genesis deposit contract received 10.336 deposits from 223 unique addresses, as fetched from the contract's Dune Analytics Board). The network started with about 170 nodes.

Supported Clients

LUKSO runs the Ethereum protocol, meaning most Ethereum clients will run the LUKSO Blockchain. The currently tested clients are the following:

CLI Development

Not all tested clients are fully supported by the LUKSO CLI yet. You can follow the latest development process on the official LUKSO CLI repository. Version 0.6.0 features Geth, Erigon, and Prysm. We are currently working to ensure that Lighthouse also receives full support.

Starting a Node

To start your clients and contribute to the blockchain network, you have 3 options:

  • Install the LUKSO CLI: The LUKSO CLI is a command line tool to install, manage and set up nodes and validators of different clients for the LUKSO blockchain. It provides simple and unified commands to interact with your node and runs natively on your operating system. We recommend this as default for anyone beginning to get into the topic of running a node himself.
  • Use Docker Compose: The official Docker Containers can make it easy for you if you're already experienced with the Docker ecosystem. Different configurations can be started in the blink of an eye and work in encapsulated containers. The versatility makes it especially useful if you want to run multiple networks on your node at once. The repository features extended documentation. By default, the Docker setup will run as a validator.
  • Configure a LUKSO Compatible Client: You are in no way limited to the tools we provide for easy onboarding. If you are a pro user, you can download and run the Erigon, Geth, Lighthouse, or Prysm clients in your preferred setup. You can either download or generate the genesis files of the LUKSO network and configure your clients manually. Please refer to the respective clients installation instructions and use the LUKSO network configuration repository to start your node.

LUKSO CLI Node Setup

You can use the LUKSO CLI to prepare and run your LUKSO mainnet node. For further information, you can check out the official LUKSO CLI Documentation. It is not limiting yourself to running any supported clients, as all configurations and flags can be passed down. The guide will give you a brief introduction.

Install the LUKSO CLI

First, install the lukso command globally on your node machine.

$ curl | sh

Create a Working Directory

Next, create a working directory for your node's data and move into it. The directory is where everything regarding your blockchain node will be stored. Make sure to choose a proper name for your node folder. If you plan on running a validator later, this folder will also contain your validator key files by default.

$ mkdir myLUKSOnode && cd myLUKSOnode

Initialize the working folder, which will download the LUKSO network configuration and genesis files needed to sync with the LUKSO network.


As the network did not launch yet, the CLI will warn that the genesis files could not have been loaded. This behaviour is as expected. Currently, only genesis validators can launch the network. They have the free choice of which genesis files to start the network with. After the launch is initialized, the network will reorganize to the majority, and the final version will be transferred to the CLI.

$ lukso init

Install the Clients

After the initialization is successful, we must download the blockchain clients, which will be managed from the CLI under the hood. They will install globally, need superuser permissions, and are set as default clients within your working directories configuration file. You will be asked which clients you want to download and install during the setup.

$ sudo lukso install

Start the Clients

The following command will spin up your execution and consensus client and connect to the mainnet.

lukso start

Checking Processes

To check that everything is running correctly, you can see the status of all your clients using the status command. By default, the validator is not enabled. If you want to run your validator node, please have a look at the validator page.

$ lukso status

# INFO[0000] PID 39424 - Execution (geth): Running 🟢
# INFO[0000] PID 39430 - Consensus (prysm): Running 🟢
# INFO[0000] PID 39432 - Validator (validator): Stopped 🔘

If you want to check any of the running clients in more detail, you can use the built-in logging command of the CLI. It will print out the current log messages of one client to the terminal screen.

# Viewing the logs of the execution client
$ lukso logs execution

# Viewing the logs of the consensus client
$ lukso logs consensus

For more options, please check the LUKSO CLI Documentation.

To enable more advanced monitoring for your node, you can check the official network-docker-monitoring repository with a step-by-step guide.

Need Help?

Check the Network FAQ section.

Ask your question in the validators channel on the official LUKSO Discord server.

Further Information