rename --metrics-port to --api-port in zeam-cmd.sh

README.md

@@ -54,6 +54,9 @@ NETWORK_DIR=local-devnet ./spin-node.sh --node all --generateGenesis --deploymen
 # Run only zeam_0 and ream_0 nodes (comma-separated)
 NETWORK_DIR=local-devnet ./spin-node.sh --node zeam_0,ream_0 --generateGenesis --popupTerminal
 
+# Run zeam_0 with a custom Docker image override (without editing client-cmds)
+NETWORK_DIR=local-devnet ./spin-node.sh --node zeam_0 --generateGenesis --docker-image ghcr.io/your-org/custom-zeam:dev
+
 # Run only zeam_0 and qlean_0 nodes (space-separated)
 NETWORK_DIR=local-devnet ./spin-node.sh --node "zeam_0 qlean_0" --generateGenesis --popupTerminal
 
@@ -119,6 +122,10 @@ NETWORK_DIR=local-devnet ./spin-node.sh --node all --generateGenesis --metrics
    - If not provided, defaults to `latest` for zeam, ream, and lantern, and `dd67521` for qlean
    - The script will automatically pull the specified Docker images before running containers
    - Example: `--tag devnet0` or `--tag devnet1`
+11. `--docker-image` specifies a full Docker image reference (image[:tag]) to override the default client image.
+   - Applies to Docker mode only; the override is injected into the `node_docker` command for the selected nodes.
+   - Useful for testing local builds or custom tags without modifying `client-cmds/*-cmd.sh`.
+   - Example: `--docker-image ghcr.io/your-org/custom-zeam:dev`
 12. `--metrics` enables metrics collection on all nodes. When specified, each client will activate its metrics endpoint according to its implementation. Metrics ports are configured per node in `validator-config.yaml`.
 
 ### Clients supported

client-cmds/qlean-cmd.sh

@@ -17,7 +17,7 @@ node_binary="$scriptDir/qlean/build/src/executable/qlean \
       --prometheus-port $metricsPort \
       -ldebug"
 
-node_docker="qdrvm/qlean-mini:3a96a1f \
+node_docker="qdrvm/qlean-mini:273cfa1 \
       --genesis /config/config.yaml \
       --validator-registry-path /config/validators.yaml \
       --validator-keys-manifest /config/hash-sig-keys/validator-keys-manifest.yaml \

client-cmds/zeam-cmd.sh

@@ -12,15 +12,15 @@ node_binary="$scriptDir/../zig-out/bin/zeam node \
       --data-dir $dataDir/$item \
       --node-id $item --node-key $configDir/$item.key \
       $metrics_flag \
-      --metrics_port $metricsPort"
+      --api-port $metricsPort"
 
-node_docker="--security-opt seccomp=unconfined blockblaz/zeam:devnet1 node \
+node_docker="--security-opt seccomp=unconfined blockblaz/zeam:latest node \
       --custom_genesis /config \
       --validator_config $validatorConfig \
       --data-dir /data \
       --node-id $item --node-key /config/$item.key \
       $metrics_flag \
-      --metrics_port $metricsPort"
+      --api-port $metricsPort"
 
 # choose either binary or docker
-node_setup="docker"
+node_setup="docker"

parse-env.sh

@@ -76,6 +76,11 @@ while [[ $# -gt 0 ]]; do
       shift # past argument
       shift # past value
       ;;
+    --docker-image)
+      dockerImageOverride="$2"
+      shift # past argument
+      shift # past value
+      ;;
     --stop)
       stopNodes=true
       shift
@@ -109,4 +114,5 @@ echo "generateGenesis = $generateGenesis"
 echo "cleanData = $cleanData"
 echo "popupTerminal = $popupTerminal"
 echo "dockerTag = ${dockerTag:-latest}"
+echo "dockerImageOverride = ${dockerImageOverride:-<none>}"
 echo "enableMetrics = $enableMetrics"

spin-node.sh

@@ -258,6 +258,13 @@ for item in "${spin_nodes[@]}"; do
   then
     execCmd="$node_binary"
   else
+    # If a docker image override was provided, replace the image name in node_docker
+    if [ -n "$dockerImageOverride" ]; then
+      # Replace the first token containing ':' (image:tag pattern) with the override image
+      # This handles cases where node_docker may start with flags like --security-opt
+      node_docker="$(echo "$node_docker" | sed -E "s|([^ ]+:[^ ]+)|$dockerImageOverride|1")"
+    fi
+
     # Extract image name from node_docker (find word containing ':' which is the image:tag)
     docker_image=$(echo "$node_docker" | grep -oE '[^ ]+:[^ ]+' | head -1)
     # Pull image first 
@@ -272,6 +279,11 @@ for item in "${spin_nodes[@]}"; do
       execCmd="sudo $execCmd"
     fi;
 
+    # Use --network host for peer-to-peer communication to work
+    # On macOS Docker Desktop, containers share the VM's network stack, allowing them
+    # to reach each other via 127.0.0.1 (as configured in nodes.yaml ENR records).
+    # Note: Port mapping (-p) doesn't work with --network host, so metrics endpoints
+    # are not directly accessible from the macOS host. Use 'docker exec' to access them.
     execCmd="$execCmd --name $item --network host \
           -v $configDir:/config \
           -v $dataDir/$item:/data \