> ## Documentation Index > Fetch the complete documentation index at: https://docs.berachain.com/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart: Run a Node > Prerequisites, scripts, and steps to run Beacon-Kit and Bera-Reth on Linux or Mac. 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: 1. **Beacon-Kit**: Download the appropriate binary from the [releases page](https://github.com/berachain/beacon-kit/releases) for your OS and architecture. Make it executable and place it in your PATH (e.g., `~/.local/bin/`). 2. **Execution client**: Download [Bera-Reth](https://github.com/berachain/bera-reth/releases) for your OS and architecture. Make it executable and place it in your PATH. See [EVM Execution Clients](/nodes/architecture/evm-execution) for recommended versions. Verify installation: ```bash theme={null} beacond version bera-reth --version ``` ## What you'll do 1. **Download scripts** — clone helper scripts that automate configuration 2. **Configure environment** — set environment variables for your network (mainnet or Bepolia) and node identity 3. **Fetch parameters** — download genesis files and network configuration 4. **Set up Beacon-Kit** — initialize the consensus client and generate keys 5. **Set up execution client** — initialize Reth with the genesis state 6. **Fetch snapshots (optional)** — restore snapshots to speed up initial sync 7. **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](https://github.com/berachain/beacon-kit/pkgs/container/beacon-kit) or [community-maintained Ansible playbooks](https://github.com/RhinoStake/ansible-berachain) that deploy docker containers. For local experimentation with validator mechanics, see [Local Devnet with Kurtosis](/nodes/guides/local-devnet-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. ```bash theme={null} # 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: ```bash env.sh theme={null} #!/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: 1. **CHAIN\_SPEC**: Set to `testnet` or `mainnet`. 2. **MONIKER\_NAME**: A name of your choice for your node. 3. **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. 4. **EL\_ARCHIVE\_NODE**: Set to `true` if you want the execution client to be a full archive node. 5. **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: ```bash theme={null} # 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: 1. 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. 2. 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`. 3. Rewrites the `beacond` configuration files to reflect settings chosen in `env.sh`. 4. Places the mainnet parameters where Beacon-Kit expects them and shows you an important hash from the genesis file. ```bash theme={null} # 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`. ```bash theme={null} # 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 Berachain and the community offer snapshots for Mainnet and Bepolia. You can download snapshots at the following links. * [Awesome Berachain Validators](https://github.com/chuck-bear/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. ```bash theme={null} # 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 testnet --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 `testnet` (default: `mainnet`; selects the snapshot index host as above) * `--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: ```bash theme={null} # 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`: ```bash theme={null} # 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`. Extracting into `var/reth/` would place `db/` next to `genesis.json` and would not match `--datadir`. ```bash theme={null} # 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: ```bash theme={null} # 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: ```bash theme={null} # 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: ```bash theme={null} # 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 ```bash theme={null} 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 ```bash theme={null} 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](/nodes/operations/production-checklist)** — Best practices for running nodes in production * **[Monitoring](/nodes/operations/monitoring)** — Set up monitoring and alerts for your node * **[Become a Validator](/nodes/guides/become-a-validator)** — Guide to becoming a validator on Berachain