Running the Node

The base-reth-node binary starts the Base L2 execution client once you have a source build or Docker image. For production guidance, see Node Operations.

Starting the Node

Run the binary directly from the build output directory:

./target/release/base-reth-node

That path assumes a release build. just build node is a debug build instead, so its binary sits elsewhere:

./target/debug/base-reth-node

The node will begin syncing from the network. On the first run it creates a data directory (by default ~/.local/share/reth/ on Linux, ~/Library/Application Support/reth/ on macOS) and starts downloading blocks.

CLI Help

View all available options and subcommands:

./target/release/base-reth-node --help

This prints the full help text including every flag, option, and subcommand. It is the definitive reference for the CLI and is always in sync with the version you built.

Common Options

Data Directory

Override the default data directory:

./target/release/base-reth-node --datadir /mnt/ssd/base-node

HTTP JSON-RPC

Enable the HTTP JSON-RPC server:

./target/release/base-reth-node \
  --http \
  --http.addr 127.0.0.1 \
  --http.port 8545

By default the server only listens on localhost. Set --http.addr 0.0.0.0 to accept connections from other machines (make sure your firewall is configured appropriately).

WebSocket JSON-RPC

Enable the WebSocket server alongside (or instead of) HTTP:

./target/release/base-reth-node \
  --ws \
  --ws.addr 127.0.0.1 \
  --ws.port 8546

Logging

Control log verbosity with the -v flag (can be repeated) or the RUST_LOG environment variable:

# Increase verbosity
./target/release/base-reth-node -vvv

# Fine-grained control via RUST_LOG
RUST_LOG=info,reth=debug ./target/release/base-reth-node

Metrics

Enable the Prometheus metrics endpoint:

./target/release/base-reth-node \
  --metrics 127.0.0.1:9001

Point your Prometheus instance at http://<host>:9001/metrics to scrape node metrics.

Example: Full Node with RPC

A typical invocation that enables both HTTP and WebSocket RPC, metrics, and stores data on a dedicated volume:

./target/release/base-reth-node \
  --datadir /data/base-node \
  --http \
  --http.addr 0.0.0.0 \
  --http.port 8545 \
  --ws \
  --ws.addr 0.0.0.0 \
  --ws.port 8546 \
  --metrics 0.0.0.0:9001 \
  -vv

Enabling Flashblocks

A synced node can serve ~200ms pre-confirmations to your applications once it is subscribed to the Flashblocks stream. Point the node at the Flashblocks WebSocket feed with RETH_FB_WEBSOCKET_URL when you launch it:

RETH_FB_WEBSOCKET_URL="wss://mainnet.flashblocks.base.org/ws" ./target/release/base-reth-node

Network	URL
Mainnet	wss://mainnet.flashblocks.base.org/ws
Sepolia	wss://sepolia.flashblocks.base.org/ws

These WebSocket URLs are part of the node infrastructure and are not meant for direct use by applications — your own RPC endpoint is what apps should query for Flashblocks data. The binary tails this stream, caches the pre-confirmation data, and replies from that cache when a Flashblocks-aware RPC method is called. The full message schema is documented in the Flashblocks API Overview.

To confirm it is working, request a pending block:

curl -X POST \
  --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["pending", false],"id":1}' \
  http://localhost:8545

A working setup returns data from the most recent Flashblock; if the stream is briefly unavailable the node falls back to the latest finalized block.

Historical Proofs RPCs

Serving eth_getProof, debug_executionWitness, and debug_executePayload at scale requires the historical proofs execution extension (ExEx), which maintains a dedicated database of the state those methods need. That database can grow by hundreds of gigabytes and wants a host with strong I/O, so enable it only if you actually need these endpoints — most operators do not.

The official execution entrypoint needs two environment variables to turn the ExEx on. It checks both, and if the storage path is empty it quietly starts the node without the ExEx:

RETH_HISTORICAL_PROOFS=true
RETH_HISTORICAL_PROOFS_STORAGE_PATH=<path>

With both set, the entrypoint runs the idempotent proofs init step and then starts the node with --proofs-history --proofs-history.storage-path=<path>. The first start backfills existing state into that proofs database, which takes roughly 24-48 hours on mainnet. You can skip it entirely by restoring a proofs snapshot.

The earliest block these RPCs can answer for is whichever block the ExEx first ran from. When the ExEx is active the --rpc.eth-proof-window flag has no effect.

Retention is set by --proofs-history.window (alias --proofs.window), counted in blocks rather than days. Because it is a block count, the time it covers depends on block time:

Build	Default window	At 2s blocks	At 200ms blocks
v1.4.2 and earlier	1296000	30 days	3 days
main since late September 2026 (#5362)	6480000	150 days	15 days

The new default is sized for 200ms blocks under Denim. Until Denim activates, a node on the new default keeps five times as much history as before, so plan disk for that or set the window yourself. The same change lowers the minimum from just over 12 hours of 2s blocks to a single block.

The entrypoint has no variable of its own for the window, and the RETH_PROOFS_HISTORY_WINDOW variable that some guides mention is not read by it. To set the flag through the official image, append it to RETH_PRUNING_ARGS, which the entrypoint passes through to the node unchanged.

The ExEx is fastest when it stays within 1024 blocks of the chain tip, so performance suffers while syncing up to head, and on an initial Base Mainnet sync it can fall behind far enough that it never catches up unaided. To prevent that, run base-consensus in follow mode so it tracks within 512 blocks of the proofs ExEx:

BASE_NODE_SOURCE_L2_RPC=<trusted_rpc>
BASE_NODE_PROOFS=true

When the ExEx reports state-root and execution durations of 0, it is keeping up correctly — it is not re-executing blocks, only persisting data from already-executed ones.

Stopping the Node

Send SIGINT (Ctrl+C) or SIGTERM to gracefully shut down the node. It will flush pending state to disk before exiting. Avoid sending SIGKILL unless absolutely necessary, as it can leave the database in an inconsistent state requiring a repair on next startup.

Next Steps

• Development Workflow — learn the day-to-day check, test, and fix commands.
• Local Devnet — spin up a full local network for integration testing.
• Configuration — detailed configuration reference for production deployments.