Quickstart: Run a Node

A Berachain node consists of two clients running together: a consensus client (BeaconKit) 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, 32GB RAM
Storage	1TB minimum (more for long-term); Local SSD or on-instance storage preferred; network volumes require at least 1000 IOPS

Software

Check EVM Execution Clients for the current recommended Beacon Kit and Bera-Reth releases for your network, then download each binary from its GitHub release page:

BeaconKit — on the Beacon Kit releases page, open the tagged release for your network and download the build for your OS and architecture. Make it executable and place it in your PATH (e.g., ~/.local/bin/).
Bera-Reth — on the Bera-Reth releases page, open the matching tagged release and download the build for your OS and architecture. Make it executable and place it in your PATH.

Verify installation:

beacond version
bera-reth --version

Both commands should report the release listed for your network on EVM Execution Clients.

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 consensus-layer genesis and network configuration
Set up BeaconKit — initialize the consensus client and generate keys
Set up execution client — initialize the Reth datadir for your chain
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 downloads consensus-layer configuration files. setup- and run- scripts start 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=mainnet   # mainnet or bepolia
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: Set to mainnet or bepolia.
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 consensus-layer network parameters for the chain you configured:

# FROM: ~/beranode

./fetch-berachain-params.sh;

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

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

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

Step 4 - Set up BeaconKit

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 network parameters where BeaconKit 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: …
# ✓ 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
# ✓ BeaconKit 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 the Reth datadir and initializes it with --chain set to your configured network (mainnet or bepolia). Pruning follows the EL_ARCHIVE_NODE setting in env.sh.

# FROM: ~/beranode

./setup-reth.sh;

# [Expected Output]:
# RETH_DATA: /.../var/reth/data
# RETH_BIN: /.../bin/bera-reth
#   Chain: mainnet
#   Version: …
# ✓ Reth set up.

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

Berachain and the community offer snapshots for Mainnet and Bepolia. You can download snapshots at the following links.

Awesome Berachain Validators is a community-maintained list; all of them have great download speed.
Or, use 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 (or any directory — use -o to change download folder)

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

# Examples:
node fetch-berachain-snapshot.js --network bepolia --type archive
node fetch-berachain-snapshot.js -o /var/snapshots --execution-only

# [Expected Output]:
# Bera Snapshot Downloader
# -------------------------
# Network: mainnet
# Client: reth
# Type: pruned
#
# Fetching snapshot index from:
#   https://snapshots.berachain.com/index.csv
# [...]
# ✓ All downloads completed!

Available options:

--network or -n: mainnet or bepolia (default: mainnet)
--type or -t: pruned or archive (default: pruned)
--output or -o: Download directory (default: downloads in the current working directory)
--el-client: Execution snapshot type prefix in the CSV (default: reth)
--beacon-only: Beacon-kit snapshot only
--execution-only or --el-only: Execution-layer snapshot only
--help or -h: Show help message

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/data;

# [Expected Output]:
# (empty or prior db contents)

rm -r var/reth/data;
mkdir -p var/reth/data;

6d - Install BeaconKit 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

Official Reth snapshot archives list db/, rocksdb/, and blobstore/ at the root of the tarball (not under a data/ directory). Your bera-reth node --datadir must be the directory that contains those folders. In this layout that is var/reth/data (see setup-reth.sh / env.sh), so pass -C var/reth/data to tar.

# 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/data;

# [Expected Output] (current official bundles):
# x db/
# x db/mdbx.dat
# x rocksdb/
# x blobstore/
# ...

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 …
# [AFTER BLOCKS START FLOWING]
# INFO processExecutionPayload ... height=49 ...
# INFO Finalized block ... height=49 ...

In the second, run the execution client:

# 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

​Prerequisites

​Hardware

​Software

​What you’ll do

​Step 1 - Download scripts

​Step 2 - Configure environment

​Step 3 - Fetch parameters

​Step 4 - Set up BeaconKit

​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 BeaconKit 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 BeaconKit

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 BeaconKit 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