Quickstart: Run a Node

A Berachain node consists of two clients running together: a consensus client (Beacon-Kit) and an execution client (Bera-Reth). This guide walks you through setting up both on a Linux or Mac computer.

Prerequisites

Hardware

Component	Requirement
OS	Linux AMD64, Linux ARM64
CPU / RAM	4 Physical Cores, 16GB RAM
Storage	1TB minimum (more for long-term); Local SSD or on-instance storage preferred; network volumes require at least 1000 IOPS

Software

Install the required binaries before starting:

Beacon-Kit: Download the appropriate binary from the releases page for your OS and architecture. Make it executable and place it in your PATH (e.g., ~/.local/bin/).
Execution client: Download Bera-Reth for your OS and architecture. Make it executable and place it in your PATH.

See EVM Execution Clients for recommended versions. Verify installation:

beacond version
bera-reth --version

What you’ll do

Download scripts — clone helper scripts that automate configuration
Configure environment — set environment variables for your network (mainnet or Bepolia) and node identity
Fetch parameters — download genesis files and network configuration
Set up Beacon-Kit — initialize the consensus client and generate keys
Set up execution client — initialize Reth with the genesis state
Fetch snapshots (optional) — restore snapshots to speed up initial sync
Run both clients — launch them in separate terminals; they communicate via JWT auth

Optional step 8 covers testing your node’s RPC endpoints.

For production deployments, consider docker images or community-maintained Ansible playbooks that deploy docker containers. For local experimentation with validator mechanics, see Local Devnet with Kurtosis.

Step 1 - Download scripts

Make an area to work in, then clone the Berachain node scripts. These scripts handle configuration, parameter fetching, and client startup.

If you’re a Unix traditionalist, use /opt/beranode as your working directory.

# FROM: $HOME

mkdir beranode;
cd beranode;
git clone https://github.com/berachain/guides;
mv guides/apps/node-scripts/* ./;
rm -r guides;
ls;

# [Expected output, edited for clarity]
# README.md                     run-reth.sh     setup-reth.sh
# env.sh                        run-beacond.sh  setup-beacond.sh
# fetch-berachain-params.sh

The file env.sh contains environment variables used in the other scripts. fetch-berachain-params.sh obtains copies of the genesis file and other configuration files. Then we have setup- and run- scripts for the execution client and beacond.

Step 2 - Configure environment

Edit env.sh to set your node’s configuration. Open the file and modify these values:

env.sh

#!/bin/bash

# CHANGE THESE VALUES
export CHAIN_SPEC=mainnet   # or "testnet"
export MONIKER_NAME=camembera
export WALLET_ADDRESS_FEE_RECIPIENT=0x8b30eb59e9b2354825503d5e60845eb41d4caf36
export EL_ARCHIVE_NODE=false # set to true if you want to run an archive node on CL and EL
export MY_IP=`curl -s canhazip.com`

# VALUES YOU MIGHT WANT TO CHANGE
export LOG_DIR=$(pwd)/logs
export JWT_PATH=$BEACOND_CONFIG/jwt.hex
export BEACOND_BIN=$(command -v beacond || echo $(pwd)/beacond)
export BEACOND_DATA=$(pwd)/var/beacond
export RETH_BIN=$(command -v bera-reth || echo $(pwd)/bera-reth)

You need to set these constants:

CHAIN_SPEC: Set to testnet or mainnet.
MONIKER_NAME: A name of your choice for your node.
WALLET_ADDRESS_FEE_RECIPIENT: The address that receives priority fees for blocks sealed by your node. If your node will not be a validator, this won’t matter.
EL_ARCHIVE_NODE: Set to true if you want the execution client to be a full archive node.
MY_IP: Sets the IP address your chain clients advertise to other peers on the network. In a cloud environment such as AWS or GCP where you are behind a NAT gateway, you must specify this address or allow the default curl canhazip.com to auto-detect it.

You should verify these constants:

LOG_DIR: This directory stores log files.
BEACOND_BIN: Set this to the full path where you installed beacond. The expression provided finds it in your $PATH.
BEACOND_DATA: Set this to where the consensus data and config should be kept.
RETH_BIN: Set this to the full path where you installed bera-reth. The expression provided finds it in your $PATH.

Step 3 - Fetch parameters

The fetch-berachain-params.sh script downloads the key network parameters for the chain you have configured:

# FROM: ~/beranode

./fetch-berachain-params.sh;

# [Expected Output for mainnet - verify these checksums]:
# c66dbea5ee3889e1d0a11f856f1ab9f0  seed-data-80094/genesis.json
# 6b333924b81a1935e51ac70e7d9d7cb0  seed-data-80094/eth-genesis.json
# 5d0d482758117af8dfc20e1d52c31eef  seed-data-80094/kzg-trusted-setup.json

# [Expected Output for bepolia - verify these checksums]:
# a24fb9c7ddf3ebd557300e989d44b619  seed-data-80069/genesis.json
# c27c1162af33f7f5401bcef974a64454  seed-data-80069/eth-genesis.json
# 5d0d482758117af8dfc20e1d52c31eef  seed-data-80069/kzg-trusted-setup.json

Verify that the checksums for genesis.json, eth-genesis.json, and kzg-trusted-setup.json match the values above for your chosen network.

Step 4 - Set up Beacon-Kit

The script setup-beacond.sh invokes beacond init and beacond jwt generate. This script:

Runs beacond init to create the file var/beacond/config/priv_validator_key.json. This contains your node’s private key. Especially if you intend to become a validator, keep this file safe. It cannot be regenerated, and losing it means you will not be able to participate in the consensus process.
Runs beacond jwt generate to create the file jwt.hex. This contains a secret shared between the consensus client and execution client so they can securely communicate. If you suspect it has been leaked, delete it then generate a new one with beacond jwt generate -o $JWT_PATH.
Rewrites the beacond configuration files to reflect settings chosen in env.sh.
Places the mainnet parameters where Beacon-Kit expects them and shows you an important hash from the genesis file.

# FROM: ~/beranode

./setup-beacond.sh;

# [Expected Output]:
# BEACOND_DATA: /.../var/beacond
# BEACOND_BIN: /.../bin/beacond
#   Version: v1.1.3
# ✓ Private validator key generated in .../priv_validator_key.json
# ✓ JWT secret generated at [...]config]/jwt.hex
# ✓ Config files in [...]beacond/config updated
# [BEPOLIA] Genesis validator root: 0x3cbcf75b02fe4750c592f1c1ff8b5500a74406f80f038e9ff250e2e294c5615e
# [MAINNET] Genesis validator root: 0xdf609e3b062842c6425ff716aec2d2092c46455d9b2e1a2c9e32c6ba63ff0bda
# ✓ Beacon-Kit set up. Confirm genesis root is correct.

Your validator state root must agree with the value shown above for your chosen chain.

Step 5 - Set up the execution client

The setup-reth.sh script creates a runtime directory and configuration for the execution client. It configures the node with pruning settings according to the EL_ARCHIVE_NODE setting in env.sh.

# FROM: ~/beranode

./setup-reth.sh;

# [Expected Output]:
# INFO [BEPOLIA] Genesis block written hash=0x0207661de38f0e54ba91c8286096e72486784c79dc6a9681fc486b38335c042f
# INFO [MAINNET] Genesis block written hash=0xd57819422128da1c44339fc7956662378c17e2213e669b427ac91cd11dfcfb38
# ✓ bera-reth set up.

Your genesis block hash must agree with the above for your chosen chain.

Step 6 - Fetch snapshots (optional)

Snapshots are collections of files from a node’s backend that represent its state at a specific time. Restoring a snapshot is much faster than syncing from the network, so this step can dramatically speed up your initial sync on a new node.

Do this step before starting your clients (Step 7). If you’ve already started syncing, you’ll need to stop the clients, clean the data directories, then restore snapshots.

Snapshots can be applied to both the consensus (beacond) and execution clients. Restoring both snapshots simultaneously provides the fastest sync.

6a - Obtain snapshots

The fetch-berachain-snapshot.js script — already on disk from Step 1 — downloads the latest official Berachain snapshots for both the beacon-kit consensus layer and the execution layer. It reads the snapshot index at snapshots.berachain.com, picks the most recent files matching your options, and saves them to a downloads/ directory.

# FROM: ~/beranode

# Default: mainnet, pruned
node fetch-berachain-snapshot.js

# Or specify options:
node fetch-berachain-snapshot.js --network testnet --type archive

# [Expected Output]:
# Bera Snapshot Downloader
# -------------------------
# Network: mainnet | Client: reth | Type: pruned
#
# Fetching snapshot index from:
#   https://snapshots.berachain.com/index.csv
#
# Will download the following files:
#   snapshot_beacon-kit-pruned_<block>.tar.lz4 (beacon)
#   snapshot_reth-pruned_<block>.tar.lz4 (execution layer)
#
# ✓ All downloads completed!

Available options:

Flag	Description	Default
`--network`, `-n`	`mainnet` or `testnet`	`mainnet`
`--type`, `-t`	`pruned` or `archive`	`pruned`
`--help`, `-h`	Show help message	—

Community-operated snapshot mirrors are listed in Awesome Berachain Validators. These are a good alternative if you prefer a different download source.

6b - Stop clients

If you’ve already started your clients, shut down beacond and your execution client now. Otherwise, skip to 6c.

6c - Clean existing chain data

To clean the Beacon Kit and reth data store:

# FROM: ~/beranode

source env.sh;
$BEACOND_BIN --home $BEACOND_HOME comet unsafe-reset-all;

# [Expected Output]:
# Removed all blockchain history dir=var/beacond/data
# Reset private validator file to genesis state key=..

ls var/reth;

# [Expected Output]:
# data  genesis.json

rm -r var/reth/data;

6d - Install Beacon-Kit snapshot

The snapshots distributed by Berachain are designed to be installed in the beacond home directory, which contains both config and data:

# FROM: ~/beranode

# Find the beacon-kit snapshot file (filename pattern: snapshot_beacon-kit-*)
BEACON_SNAPSHOT=$(ls downloads/snapshot_beacon-kit-*.tar.lz4 | head -1)
lz4 -d "$BEACON_SNAPSHOT" | tar xv -C var/beacond/;

# [Expected Output]:
# x data/
# x data/cs.wal/
# x data/cs.wal/wal.10416
# ...

6e - Install execution layer snapshot

Extract the execution layer snapshot:

# FROM: ~/beranode

# Find the execution layer snapshot
EL_SNAPSHOT=$(ls downloads/snapshot_reth-*.tar.lz4 | head -1)
lz4 -d "$EL_SNAPSHOT" | tar xv -C var/reth/;

# [Expected Output]:
# x data/
# x data/db/
# x data/db/mdbx.dat
# x data/static_files/
# ...

Step 7 - Run both clients

Launch two terminal windows. In the first, run the consensus client:

# FROM: ~/beranode

./run-beacond.sh;

# [Expected Output]:
# INFO Waiting for execution client to start... 🍺🕔
# INFO Connected to execution client
# INFO Reporting version v1.1.3
# [AFTER BLOCKS START FLOWING]
# INFO processExecutionPayload ... height=49 ...
# INFO Finalized block ... height=49 ...

In the second, run the execution client. Here it is for Bera-Reth:

# FROM: ~/beranode

./run-reth.sh;

# [Expected Output]:
# INFO RPC HTTP server started url=0.0.0.0:8545
# INFO Starting consensus engine
# [AFTER BLOCKS START FLOWING]
# INFO Block added to canonical chain number=49 hash=0xfb2ea...

Initially this will not appear to respond, but within a minute blocks should begin flowing. There should not be a significant number of error messages, except for occasional minor complaints about disconnecting or slow peers.

Both clients are running and will begin syncing with the network. The node will continue syncing in the background. You can proceed to the optional testing steps below, or leave the clients running to complete their sync.

Step 8 - Testing your node (optional)

Now that your RPC is running, verify that the network is working by performing a few RPC requests.

Make sure that your node is fully synced before proceeding with these steps.

Check sync status

To check the sync status of the consensus layer, in another terminal run the following to retrieve the current block height from the consensus client:

# FROM: ~/beranode

set -e
. ./env.sh

# Don't have jq? `brew install jq`
$BEACOND_BIN --home=$BEACOND_DATA status | jq;

# [Expected Output]:
# {
#   "sync_info": {
#     "latest_block_height": "1126228",    <---- CURRENT NETWORK BLOCK
#     "catching_up": false                 <---- IF `true` = STILL SYNCING
#   }
# }

If catching_up is set to true, it is still syncing.

EL block number

curl --location 'http://localhost:8545' \
--header 'Content-Type: application/json' \
--data '{
  "jsonrpc":"2.0",
  "method":"eth_blockNumber",
  "params":[],
  "id":420
}';

# [Expected Output]:
# {
#     "jsonrpc": "2.0",
#     "result": "0xfae90",    <---- compare with block explorer
#     "id": 420
# }

CL block number

curl -s http://localhost:26657/status | jq '.result.sync_info.latest_block_height';

# [Expected Output]:
# 1653733

Next steps

Your node is now running and syncing. For production deployments, see:

Production Checklist — Best practices for running nodes in production
Monitoring — Set up monitoring and alerts for your node
Become a Validator — Guide to becoming a validator on Berachain

Overview

BeaconKit

Architecture

Operations

Staking Pools

Guides

Help

Quickstart: Run a Node

Prerequisites

Hardware

Software

What you’ll do

Step 1 - Download scripts

Step 2 - Configure environment

Step 3 - Fetch parameters

Step 4 - Set up Beacon-Kit

Step 5 - Set up the execution client

Step 6 - Fetch snapshots (optional)

6a - Obtain snapshots

6b - Stop clients

6c - Clean existing chain data

6d - Install Beacon-Kit snapshot

6e - Install execution layer snapshot

Step 7 - Run both clients

Step 8 - Testing your node (optional)

Check sync status

EL block number

CL block number

Next steps

Overview

BeaconKit

Architecture

Operations

Staking Pools

Guides

Help

​Prerequisites

​Hardware

​Software

​What you’ll do

​Step 1 - Download scripts

​Step 2 - Configure environment

​Step 3 - Fetch parameters

​Step 4 - Set up Beacon-Kit

​Step 5 - Set up the execution client

​Step 6 - Fetch snapshots (optional)

​6a - Obtain snapshots

​6b - Stop clients

​6c - Clean existing chain data

​6d - Install Beacon-Kit snapshot

​6e - Install execution layer snapshot

​Step 7 - Run both clients

​Step 8 - Testing your node (optional)

​Check sync status

​EL block number

​CL block number

​Next steps

Prerequisites

Hardware

Software

What you’ll do

Step 1 - Download scripts

Step 2 - Configure environment

Step 3 - Fetch parameters

Step 4 - Set up Beacon-Kit

Step 5 - Set up the execution client

Step 6 - Fetch snapshots (optional)

6a - Obtain snapshots

6b - Stop clients

6c - Clean existing chain data

6d - Install Beacon-Kit snapshot

6e - Install execution layer snapshot

Step 7 - Run both clients

Step 8 - Testing your node (optional)

Check sync status

EL block number

CL block number

Next steps