Skip to main content

6.3 LUKSO CLI Installation

The LUKSO CLI is a unified command-line tool for installing, configuring, and running all officially supported execution and consensus clients on the LUKSO network with additional utility. It simplifies multi-client management by generating a single working directory with separate configs per network. This section explains, how to install and configure the LUKSO CLI to manage your blockchain clients and validators.

tip

Please ensure you have a basic understanding of blockchain networks before operating a node. If you're not yet familiar with Proof of Stake, Tokenomics, Panelties, Client Types or Client Providers, please refer to the 🧠 Theory section.

Platform Support

The LUKSO CLI is officially supported on Mac, Ubuntu, and Debian with the following architectures:

  • x86 and x86_64: Intel and AMD Processors
  • ARM and aarch64: Silicon or Single-Board Processors
Flags and Runtime

The clients started from the CLI run in the /usr/local/ directory of the operating system:

  • All client flags and additional configurations can be passed down to the services.
  • The CLI is bound to the operating system, meaning only a single node can be operated on one device.
tip

If you want to use 🐳 Docker or manual configuration, have a look at the Client Setups page in the 🧠 Theory section.

1. Install the LUKSO CLI​

Download and run the official installation script.

info

The following steps are performed on your 📟 node server.

sudo curl https://install.lukso.network | sh
note

The executable files of the lukso service will be downloaded to the /usr/local/bin/lukso directory.

2. Create a Working Directory​

Choose a directory to house all node data and configs.

2.1 Access the Home Directory: It's recommended to place all blockchain data in the home environment.

cd

2.2 Create a Node Folder: Choose a directory to house all blockchain, configuration, and node data.

info

Replace <lukso-working-directory> with a specific name for your node folder.

mkdir <lukso-working-directory>

2.3 Navigate into the Folder: Move into the working directory to initialize your node clients.

cd ./<lukso-working-directory>

3. Initialize the Working Directory​

Using the LUKSO CLI, you can download all dependencies and configuration files for all network types with one initialization.

info

The init command generates a cli-config.yaml file and a config folder within the node directory, containing the genesis files, network properties, and client-specific configurations for the bootnodes of the related LUKSO networks.

tip

To learn about bootnodes and the architecture, have a look at the Peer Networks page in the 🧠 Theory section.

lukso init
note

When asked to add your public IP address to the configuration file to improve connectivity, you can decline for now. Your public IP address may change frequently, depending on your internet provider, even if you've previously assigned a static IP on the router level. While adding your IP is a temporary improvement, this setting is overwritten once setting up a dynamic DNS for stable and long-term connectivity without ongoing maintenance.

info

During setup, a file named jwt.hex is created at at ./configs/shared/secrets/. The JSON Web Token key will be used to sign and verify the communication between the execution and consensus client of your node.

Folder Structure

The configuration folder will have separate folders for the mainnet and testnet networks.

lukso-node
│
├───configs
│   └───[network]
│   |   ├───besu                              // Config Files for Besu Client
│   |   ├───erigon                            // Config Files for Erigon Client
│   |   ├───geth                              // Config Files for Geth Client
│   |   ├───lighthouse                        // Config Files for Lighthouse Client
│   |   ├───nethermind                        // Config Files for Nethermind Client
│   |   ├───nimbus2                           // Config Files for Nimbus-Eth2 Client
│   |   ├───prysm                             // Config Files for Prysm Client
│   |   ├───teku                              // Config Files for Teku Client
│   |   └───shared
|   |       ├───config.yaml                   // Global Client Config
|   |       ├───deploy_block.txt              // Block Deployment Number
|   |       ├───deploy_contract_block.txt     // Contract Deployment Number
|   |       ├───genesis.json                  // Genesis JSON Data
|   |       └───genesis.ssz                   // Genesis Validator File
│   │
│   └───shared
│       └───secrets
│           └───jwt.hex                       // Global Communication Secret
|
└───cli-config.yaml                           // Global CLI Configuration

4. Install Blockchain Clients​

After the initialization of the node's working directory, you will be able to select which clients clients to run in the setup.

info

Clients will be installed globally at /usr/local/bin/ and set as default within your working directory.

tip

Please inform yourself about Client Providers and Client Diversity to ensure your node's and the network stability.

Staking Notice

If you want to run a validator and stake funds, choose between the Prysm, Lighthouse, or Teku consensus client.

lukso install

Check if the clients were installed correctly using their version commands:

geth --version
info

If you encounter errors during the download or checkups, re-do the installation process.

5. Node Startup​

Controlling the LUKSO CLI to start and stop your node can be done with easy commands and flags.

tip

As the LUKSO networks are running since 2023, synchronizing the full blockchain state of the network can take multiple days. Validators can utilize checkpoints to start staking with the minimum required state proofs, while the full data set is downloaded in the background. Using such checkpoints significantly reduces downtime and penalties when doing maintenance.

Synchronization ModeInitial Sync TimeDescription
Regular Synchronization4 to 20 Hours- Dowloads the full data from genesis block using other peers
- Must wait for complete download before validator is usable
- Ideal for regular or archive nodes without staking
Automated Checkpoints15 to 60 Minutes- Fetches the recently finalized checkpoint from an service endpoint
- Back‑fills historical blocks and data until genesis in the background
- Quick start for fresh installs, migrations, or recovery for stakers
- Relies on access to the public checkpoint API
Manual Checkpoints15 to 60 Minutes- Operator inputs flags and entry values manually via client flags
- Back‑fills historical blocks and data until genesis in the background
- Quick start for fresh installs, migrations, or recovery for stakers
- Risk of stale or mistyped checkpoint values
warning

Automated Checkpoints are only available in the LUKSO CLI from version 0.8 and above.

# Starting the Mainnet Node without Staking
lukso start

# Starting the Testnet Node without Staking
lukso start --testnet
tip

Details about logging client outputs can be found on the Problem Scanning page of the Maintenance section.

Folder Structure

After starting the node once, new folders were added, storing the fetched blockchain data and logs of the related network.

lukso-node
│
├───configs                                   // Configuration Files
├───[network]-logs                            // Network's Logged Status Messages
├───[network]-data                            // Network's Blockchain Data
│   ├───consensus                             // Storage for used Consensus Client
│   ├───execution                             // Storage for used Execution Client
│   └───validator                             // Storage for Validator Client
|
└───cli-config.yaml                           // Global CLI Configuration

6. Node Shutdown​

Similar to initializing and starting the node from a working directory, you can stop all running clients at once.

# Stopping the Node
lukso stop
info

Ensure to stop the node before configuring the validator keys or apply further modifications within the next steps.