How to Switch Execution Clients on Base After Initial Sync

You switch execution clients on Base by setting the CLIENT environment variable to reth, geth, or nethermind, then rebuilding the Docker images with docker compose up --build.

Base's official node implementation uses Docker Compose to orchestrate execution and consensus clients, making it straightforward to change your execution layer without reconfiguring your entire infrastructure. The repository dynamically selects client-specific Dockerfiles based on environment variables, allowing you to switch between Reth, Geth, or Nethermind even after completing an initial sync.

Understanding the Client Selection Mechanism

The Base node repository determines which execution client to run through a variable substitution pattern in docker-compose.yml. The compose file references ${CLIENT:-geth}/Dockerfile to select the appropriate build context for your chosen client.

In the default .env file, the repository sets:

CLIENT=${CLIENT:-geth}

This fallback mechanism ensures that if you do not explicitly set a CLIENT value, the node defaults to Geth. When you specify a different value, the compose file automatically targets the corresponding subdirectory (such as reth/ or nethermind/) and mounts a client-specific data directory at ./${CLIENT}-data.

Step-by-Step Guide to Switching Execution Clients on Base

Stop the Current Containers

Before changing configurations, gracefully stop the running node to prevent database corruption. Run the following command from the repository root:

docker compose down

This terminates the execution client, consensus client, and dependent services while preserving your current data volumes.

Configure the New Client

Set the CLIENT environment variable to your desired execution client. You have two options for this configuration:

• Environment file method: Edit the .env file (or network-specific files like .env.sepolia or .env.mainnet) and set CLIENT=reth, CLIENT=geth, or CLIENT=nethermind
• Command-line method: Export the variable in your shell session:

export CLIENT=reth
export NETWORK_ENV=.env.sepolia  # Optional: specify testnet or mainnet

Any explicit value you set overrides the default geth fallback defined in the repository's environment configuration.

Rebuild the Docker Images

Because each execution client uses a distinct Dockerfile and build process, you must rebuild the images after switching. Execute:

docker compose up --build -d

The --build flag forces Docker to recompile the image using the new client's Dockerfile (for example, reth/Dockerfile when CLIENT=reth). The -d flag runs the containers in detached mode.

Verify the Data Directory Strategy

By default, the Base node compose file mounts ${HOST_DATA_DIR}, which expands to ./${CLIENT}-data based on your selection. This design provides automatic data isolation—switching from Geth to Reth automatically points the volume to ./reth-data instead of ./geth-data.

If you want to preserve your previous sync progress, you must manually migrate the data:

1. Copy the database files from the old client directory (e.g., ./geth-data) to the new directory (e.g., ./reth-data)
2. Run the appropriate client-specific import tools to convert the data format (not covered in the base repository documentation)

Without manual migration, the new client starts with a fresh database and begins syncing from genesis or a checkpoint.

Start the Node

Once the images finish building, the node starts automatically with your newly selected execution client. Monitor the logs to confirm the client is initializing correctly:

docker compose logs -f reth  # or geth, nethermind

Complete Example: Switching from Geth to Reth on Sepolia

The following commands demonstrate switching from the default Geth client to Reth on the Base Sepolia testnet:

# 1. Stop existing services

docker compose down

# 2. Set environment variables for the new client

export CLIENT=reth
export NETWORK_ENV=.env.sepolia

# 3. Rebuild with the new execution client and start

docker compose up --build -d

This sequence stops the Geth container, builds the Reth image using reth/Dockerfile, and mounts data to ./reth-data. The node begins syncing with Reth's implementation of the execution layer.

Important Considerations When Switching Clients

Database Compatibility: Execution clients use different database schemas and storage formats. You cannot simply point Reth at a Geth data directory and expect it to work. Plan for a resync unless you perform a manual export/import cycle using tools specific to both the source and target clients.

Performance Characteristics: Each client offers different sync speeds, disk usage patterns, and RPC performance. Reth typically provides faster sync times and lower disk usage than Geth, while Nethermind offers different resource trade-offs. Review the client-specific README files (such as reth/README.md) in the repository for detailed benchmarks.

Network Consistency: Ensure you maintain the same NETWORK_ENV setting when switching clients. Changing both the execution client and the network simultaneously (for example, moving from mainnet Geth to sepolia Reth) can lead to confusion if data directories are not managed carefully.

Summary

• The CLIENT environment variable controls which execution client Dockerfile Base uses, defaulting to geth if unset
• Modify .env or export CLIENT=reth|geth|nethermind to switch clients
• Run docker compose down to stop services before switching, then docker compose up --build to rebuild with the new client
• Data directories automatically isolate to ./${CLIENT}-data, requiring manual migration if you want to preserve sync progress across client switches
• Each client requires rebuilding the Docker image because they use distinct Dockerfiles in their respective subdirectories

Frequently Asked Questions

Will switching execution clients preserve my existing sync data?

No, switching execution clients does not automatically preserve your sync data. The Base node configuration automatically mounts a new data directory (for example, ./reth-data when switching to Reth) that is separate from your previous client's directory. To preserve progress, you must manually copy the database files and run client-specific import tools to convert the data format, though the base repository does not provide automated tooling for this migration.

Can I switch between mainnet and testnet at the same time as switching clients?

Yes, you can switch networks and clients simultaneously by setting both the CLIENT and NETWORK_ENV variables. For example, set CLIENT=reth and NETWORK_ENV=.env.sepolia to run Reth on the Sepolia testnet. Ensure you verify that the data directory path reflects both changes to avoid accidentally mixing mainnet and testnet data.

How do I know which execution clients are supported by Base node?

The Base repository officially supports three execution clients: Geth, Reth, and Nethermind. You can identify supported clients by examining the subdirectories in the repository root—each client has its own directory (such as reth/, geth/, and nethermind/) containing a Dockerfile and specific documentation. The docker-compose.yml file references these directories dynamically using the ${CLIENT} variable.

Is it possible to run multiple execution clients simultaneously for redundancy?

The standard Base node configuration does not support running multiple execution clients simultaneously from the same compose file. The docker-compose.yml structure defines a single execution client service that references ${CLIENT}/Dockerfile. To run redundant clients, you would need to maintain separate node instances with distinct data directories and ports, then configure your consensus layer or load balancer to distribute requests between them.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}