# How to Switch Execution Clients on Base After Initial Sync

> Easily switch execution clients on Base after initial sync by setting the CLIENT environment variable and rebuilding Docker images. Learn how to change clients with reth geth or nethermind.

- Repository: [Base/node](https://github.com/base/node)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/base/node/blob/main/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:

```text
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash

# 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`](https://github.com/base/node/blob/main/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`](https://github.com/base/node/blob/main/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`](https://github.com/base/node/blob/main/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.