Quickstart: Run a Node

A Berachain node consists of two clients running together: a consensus client (Beacon-Kit) and an execution client (Bera-Reth or Bera-Geth). 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: Choose either Bera-Reth or Bera-Geth. Download the binary 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  # or bera-geth 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 or Geth with the genesis state
Fetch snapshots (optional) — restore snapshots to speed up initial sync
Fetch address book (optional) — download peer list for faster startup
Run both clients — launch them in separate terminals; they communicate via JWT auth

Optional step 9 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-geth.sh     setup-geth.sh
# env.sh                        run-reth.sh     setup-reth.sh
# fetch-berachain-params.sh     run-beacond.sh  setup-beacond.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 various execution clients 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)
export GETH_BIN=$(command -v bera-geth || echo $(pwd)/bera-geth)

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 or other chain client: Set this to the full path where you installed the chain client.

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 and setup-geth scripts create a runtime directory and configuration for their respective chain clients. The scripts configure the node with pruning settings according to the EL_ARCHIVE_NODE setting in env.sh. If you’re using Bera-Reth, run setup-reth.sh. If you’re using Bera-Geth, run setup-geth.sh instead. Here’s an example using setup-reth:

# 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 8). 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 snapshot

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 to download official Berachain snapshots. The script fetches the latest snapshots from snapshots.berachain.com and automatically downloads both the beacon-kit and execution layer snapshots matching your configuration.

# FROM: ~/beranode

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

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

# [Expected Output]:
# Bera Snapshot Downloader
# Network: mainnet | Client: reth | Type: pruned
# Fetching snapshot index...
# Will download: snapshot_beacon-kit-pruned_*.tar.lz4, snapshot_reth-pruned_*.tar.lz4
# Downloading...
# ✓ All downloads completed!

Available options:

--client or -c: Execution client (reth or geth, default: reth)
--network or -n: Network (mainnet or testnet, default: mainnet)
--type or -t: Snapshot type (pruned or archive, default: pruned)
--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;

# [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. The example below uses reth (for geth, use var/geth/ or var/bera-geth/):

# FROM: ~/beranode

# Find the execution layer snapshot
EL_SNAPSHOT=$(ls downloads/snapshot_reth-*.tar.lz4 downloads/snapshot_geth-*.tar.lz4 2>/dev/null | 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 - Fetch address book (optional)

The beacond address book contains a list of nodes to communicate with. Starting with one dramatically improves startup time.

# FROM: ~/beranode

# MAINNET
wget https://storage.googleapis.com/bera-snapshot-na/addrbook.json -O var/beacond/config/addrbook.json

# TESTNET
wget https://storage.googleapis.com/bera-testnet-snapshot-na/addrbook.json -O var/beacond/config/addrbook.json

# [Expected Output]:
#  'var/beacond/config/addrbook.json' saved

Step 8 - 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 9 - 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 snapshot

6b - Stop clients

6c - Clean existing chain data

6d - Install Beacon-Kit snapshot

6e - Install execution layer snapshot

Step 7 - Fetch address book (optional)

Step 8 - Run both clients

Step 9 - 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 snapshot

​6b - Stop clients

​6c - Clean existing chain data

​6d - Install Beacon-Kit snapshot

​6e - Install execution layer snapshot

​Step 7 - Fetch address book (optional)

​Step 8 - Run both clients

​Step 9 - 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 snapshot

6b - Stop clients

6c - Clean existing chain data

6d - Install Beacon-Kit snapshot

6e - Install execution layer snapshot

Step 7 - Fetch address book (optional)

Step 8 - Run both clients

Step 9 - Testing your node (optional)

Check sync status

EL block number

CL block number

Next steps