Skip to main content
You are replacing the execution client only. Beacon-Kit (beacond) keeps the same validator identity, consensus history, and Engine API handshake with the EL. Reth does not read Geth’s chain database. Plan to retire the Geth installation after Reth is healthy.

​
Layout

Below is an example layout on disk that we will reason with in this guide. Your installation can, of course, vary. The example below uses /srv/bera so systemd units, Compose files, and on-call runbooks all refer to the same paths. Suggested tree (adjust names to match your host): 
/srv/bera/
├── beacond/                    # Consensus home
│   ├── config/
│   │   ├── app.toml
│   │   ├── genesis.json        # CL genesis (already present)
│   │   ├── jwt.hex             # Engine secret: same file Reth reads
│   │   └── ...
│   └── data/
└── reth/
    ├── genesis.json            # EL genesis for bera-reth --chain
    └── data/                   # bera-reth node --datadir (empty until init or snapshot)
Consensus home is the directory you pass to beacond as --home. It always contains config/ and data/. For a migration, the lowest-risk approach is to take a filesystem copy of the entire beacond tree from the host that currently runs Geth, while beacond is stopped. That copy preserves priv_validator_key.json, current app.toml, config.toml, address book, and CL chain data exactly as they were under Geth. Reth datadir is where reth configuration and chain data is. In later steps you will initialize Reth here or install a snapshot.
  1. **jwt.json ** is the shared secret so Beacon-Kit and Geth can communicate. You only need one copy. Set both jwt-secret-path in Beacon-Kit’s app.toml and Reth’s --authrpc.jwtsecret to that exact full path.
  2. Execution genesis — The execution genesis JSON is required. Your copy should be fine, or download the canonical eth-genesis.json from berachain/beacon-kit, and place it in reth/genesis.json.

​
Invocation

Collect launch options from Geth before you decommission it. Open the unit file, Compose service, or shell wrapper that starts Geth today and note every path and port. Many of these are covered by reasonable Reth defaults. The guides run-reth.sh is a worked example of flags that work with Beacon-Kit; treat it as a checklist against your own systemd or kubernetes pod. Bera-Reth inherits Reth’s CLI. The full upstream option list for the node command is documented at reth node (CLI reference). Many flags are the same between Bera-Geth and Bera-Reth:
Geth (typical)Reth equivalent
--datadirsame
--chain /path/genesis.jsonsame
--http, --http.addr, --http.portsame
--authrpc.addr, --authrpc.port, --authrpc.jwtsecretsame
--nat extip:IPsame; this option is highly recommended
--port (execution P2P)--port and --discovery.port
--static-peers <peer,peer>--trusted-peers <peer,peer>
Full node vs archivePruned-style: pass --full. Full archive: omit --full
Pass --chain with your EL genesis JSON path on every bera-reth node start, not only after init. Bootnodes — Use the current mainnet or Bepolia el-bootnodes.txt with --bootnodes (comma-separated enode:// lines). Typical Reth startup structure: 
EL_BOOTNODES=$(grep '^enode://' "el-bootnodes.txt"|tr '\n' ','|sed 's/,$//')

$RETH_BIN node                           \
    --datadir $RETH_DATA                 \
    --chain $RETH_GENESIS_PATH           \
    --full                               \
    --bootnodes $BOOTNODES_OPTION        \
    --nat extip:$EXTERNAL_IP_ADDR        \
    --authrpc.jwtsecret $JWT_PATH        \
    --metrics 9101                       \
    --http                               \
    --http.addr 0.0.0.0                  \
    --http.port 8545                     \
    --ipcpath /tmp/reth.ipc              \
    --log.file.directory $LOG_DIR        \
    --engine.persistence-threshold 0     \
    --engine.memory-block-buffer-target 0

​
Option 1: Init and sync from genesis

This path is appropriate when you accept a long execution-layer sync from genesis and want minimal moving parts.
  1. Remove or rename the Geth datadir so Reth never opens it by mistake.
  2. Ensure eth-genesis.json is at your EL genesis path (EVM Execution).
  3. Initialize Reth’s database directory:
bera-reth init --datadir /srv/bera/reth/data --chain /srv/bera/reth/genesis.json
  1. After you Start (below), Reth syncs execution state from the network. Expect this to take much longer than restoring a snapshot unless you are very close to genesis.

​
Option 2: Install snapshot

Choose this path when you want to land near head on disk instead of waiting for a full EL sync.
  1. Download — Official Bera snapshots are .tar.lz4 files. The snapshot downloader is a standlone Node.js 18+ script. It accepts --help.
  -n, --network <network>     mainnet or testnet (default: mainnet)
  -t, --type <type>           pruned or archive (default: pruned)
  -o, --output <dir>          download directory (default: downloads)
      --el-client <name>      execution row prefix in CSV (default: reth)
      --beacon-only           beacon-kit snapshot only
      --execution-only, --el-only
                              execution-layer snapshot only
  -h, --help                  show this help
Example: 
curl -sO https://raw.githubusercontent.com/berachain/guides/main/apps/node-scripts/fetch-berachain-snapshot.js
node fetch-berachain-snapshot.js --execution-only -o ./downloads
Using a downloaded snapshot:
  1. Stop both beacond and the execution client before unpacking anything into the Reth datadir.
  2. Extract — Current official Reth snapshot archives place db/, rocksdb/, and blobstore/ at the tar root, not under a data/ folder. Point tar -C at your --datadir so those directories land directly inside it. For the suggested tree, --datadir is /srv/bera/reth/data and thus: 
EL_SNAPSHOT=$(ls /path/to/downloads/*reth*.tar.lz4 | head -1)
lz4 -d "$EL_SNAPSHOT" | tar xv -C /srv/bera/reth/data
If you ever see tarball paths prefixed with data/ (e.g. tar -tv shows data/db/...), unpack with -C set to the parent of --datadir instead so data/ becomes the datadir. If Reth partially synced earlier, empty --datadir before extracting.

​
Start

Start beacond and bera-reth with whatever supervisor you already use. We recommend EL, then CL. Provided the JWT path and auth RPC port agrees between Reth and Beacon-Kit (see its rpc-dial-url setting), they should connect and begin following the chain. Watch beacond logs for a successful execution-client connection. Hit your configured HTTP RPC port on Reth (often 8545) with a simple eth_blockNumber once you expect sync to move. When Reth is stable and you no longer need rollback to Geth, delete or archive the old Geth datadir to free space. For a brand-new node built entirely from the guides scripts, see Quickstart: Run a Node.