Skip to main content
Version: v0.19.0

Run a test cluster locally


This is a demo repo to understand how Distributed Validators work and is not suitable for a mainnet deployment.

This guide only runs one Execution Client, one Consensus Client, and 6 Distributed Validator Charon Client + Validator Client pairs on a single docker instance. As a consequence, if this machine fails, there will not be fault tolerance.

Follow these two guides sequentially instead for production deployment: create keys centrally and how to deploy them.

The charon-distributed-validator-cluster repo contains six charon clients in separate docker containers along with an execution client and consensus client, simulating a Distributed Validator cluster running.

The default cluster consists of:


  • Ensure you have docker installed.
  • Ensure you have git installed.
  • Make sure docker is running before executing the commands below.

Create the key shares locally

  1. Clone the charon-distributed-validator-cluster repo and cd into the directory.

    # Clone the repo
    git clone

    # Change directory
    cd charon-distributed-validator-cluster/
  2. Prepare the environment variables

    # Copy the sample environment variables
    cp .env.sample .env

    .env.sample is a sample environment file that allows overriding default configuration defined in docker-compose.yml. Uncomment and set any variable to override its value.

  3. Create the artifacts needed to run a DV cluster by running the following command:

    # Enter required validator addresses

    # Create a distributed validator cluster
    docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.19.0 create cluster --name="mycluster" --cluster-dir=".charon/cluster/" --withdrawal-addresses="${WITHDRAWAL_ADDR}" --fee-recipient-addresses="${FEE_RECIPIENT_ADDR}" --nodes 6 --network goerli --num-validators=1

These commands will create six folders within .charon/cluster, one for each node created. You will need to rename node* to .charon for each folder to be found by the default charon run command, or you can use charon run --private-key-file=".charon/cluster/node0/charon-enr-private-key" --lock-file=".charon/cluster/node0/cluster-lock.json" for each instance of charon you start.

Start the cluster

Run this command to start your cluster containers

# Start the distributed validator cluster
docker compose up --build

Check the monitoring dashboard and see if things look all right

# Open Grafana
open http://localhost:3000/d/laEp8vupp