Skip to main content
Version: 2.4.3

Configure the Development Environment

This document describes how to configure a local development environment for Chaos Mesh.

Most components of Chaos Mesh are designed only for Linux, so we suggest that you also configure your development environment to run on Linux. For example, using a virtual machine or WSL 2, and using VSCode Remote as your editor.

This document assumes that you use Linux, without the restriction on specific Linux distributions. If you persist to use Windows/MacOS, you might need some tricks to make it work by yourself.

Configuration Requirements

Before configuring, we suggest to install the development tools for Chaos Mesh.

Compiling Chaos Mesh

After installing the above tools, follow the steps below to configure the toolchain for compiling Chaos Mesh.

  1. Clone the Chaos Mesh repository to your local server.

    git clone
    cd chaos-mesh
  2. Make sure that Docker is installed and running in your environment.

  3. Compile Chaos Mesh:

    UI=1 make

    You should get these container images:


Run Chaos Mesh in Local minkube Kubernetes Cluster

After compiling Chaos Mesh, you can run Chaos Mesh in a local Kubernetes cluster.

  1. Start a local Kubernetes cluster with minkube.

    minikube start
  2. Load container images into minikube

    minikube image load
    minikube image load
    minikube image load
  3. Install Chaos Mesh by Helm

    helm upgrade --install chaos-mesh-debug ./helm/chaos-mesh --namespace=chaos-mesh-debug --create-namespace

minikube image load would cost lots of time, so here is a trick to avoid load images again and again. Using docker from minikube node instead of host's docker.

minikube start --mount --mount-string "$(pwd):$(pwd)"
eval $(minikube -p minikube docker-env)
UI=1 make

Debug Chaos Mesh in local environment

We could use delve with remote debugging to debug the Chaos Mesh in local environment.

  1. Compile Chaos Mesh with Debug Info

    UI=1 DEBUGGER=1 make
  2. Load container images into minikube

    minikube image load
    minikube image load
    minikube image load
  3. Install Chaos Mesh by Helm with Enabling Remote Debugging

    helm upgrade --install chaos-mesh-debug ./helm/chaos-mesh --namespace=chaos-mesh-debug --create-namespace --set chaosDlv.enable=true --set controllerManager.replicaCount=1

    We would set 3 replicas for chaos-controller-manager for HA purpose, --set controllerManager.replicaCount=1 would create 1 instance of chaos-controller-manager for easier debugging.

  4. Setup Port-Forwarding and Configure IDE To Connect the Remote Debugger

    We could use kubectl port-forward for port-forwarding the delve debugging server on a local port.

    For example, if we want to debug chaos-controller-manger, we could execute the following command:

    kubectl -n chaos-mesh-debug port-forward chaos-controller-manager-766dc8488d-7n5bq 58000:8000

    Then we could access the remote delve debugger server with


    We always use 8000 in the pod for serving the delve debug server, that's a convention. You could find that in helm templates files.

    Then we could configure our favorite IDE to connect to the remote debugger:

    For Goland, see Attach to running Go processes with the debugger#Attach to a process on a remote machine.

    For VSCode, see vscode-go - Debugging#Remote Debugging.

For more detailed information, see for container image chaos-dlv.

Learn more

After finishing the above preparation, you can try to Add a New Chaos Experiment type.