Skip to main content
Version: v0.16.0

Run a test cluster locally


This is a demo repo to understand how Distributed Validators work and is not suitable for a production 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.16.0 create cluster --name="mycluster" --withdrawal-addresses="${WITHDRAWAL_ADDR}" --fee-recipient-addresses="${FEE_RECIPIENT_ADDR}" --nodes 6 --threshold 5

These commands will create a subdirectory .charon/cluster. In it are six folders, one for each charon node created. Each folder contains partial private keys that together make up the distributed validator described in .charon/cluster/cluster-lock.json.

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