Documentation

• 1: Simple Solo Setup
• 1.1: System Readiness
• 1.2: Quickstart
• 1.3: Managing Your Network
• 1.4: Cleanup
• 2: Advanced Solo Setup
• 2.1: Using Environment Variables
• 2.2: Network Deployments
• 2.2.1: One-shot Falcon Deployment
• 2.2.2: Falcon Values File Reference
• 2.2.3: Step-by-Step Manual Deployment
• 2.2.4: Dynamically add, update, and remove Consensus Nodes
• 2.3: Attach JVM Debugger and Retrieve Logs
• 2.4: Customizing Solo with Tasks
• 2.5: Solo CI Workflow
• 2.6: CLI Reference
• 2.6.1: Solo CLI Reference
• 2.6.2: CLI Migration Reference
• 3: Using Solo
• 3.1: Accessing Solo Services
• 3.1.1: Using Solo with Mirror Node
• 3.2: Using Solo with Hiero JavaScript SDK
• 3.3: Using Solo with EVM Tools
• 3.4: Using Network Load Generator with Solo
• 4: Troubleshooting
• 5: Community Contributions
• 6: FAQs

1 - Simple Solo Setup

1.1 - System Readiness

Overview

Before you deploy a local Hiero test network with solo one-shot single deploy, your machine must meet specific hardware, operating system, and tooling requirements. This page walks you through the minimum and recommended memory, CPU, and storage, supported platforms (macOS, Linux, and Windows via WSL2), and the required versions of Docker/Podman, Node.js, and Kubernetes tooling. By the end of this page, you will have your container runtime installed, platform-specific settings configured, and all Solo prerequisites in place so you can move on to the Quickstart and create a local network with a single command.

Hardware Requirements

Solo’s resource requirements depend on your deployment size:

Note: If you are using Docker Desktop, ensure the resource limits under Settings → Resources are set to at least these values - Docker caps usage independently of your machine’s total available memory.

Software Requirements

Solo manages most of its own dependencies depending on how you install it:

• Homebrew install (brew install hiero-ledger/tools/solo) - automatically installs Node.js in addition to Solo.
• one-shot commands — automatically install Kind, kubectl, Helm, and Podman (an alternative to Docker) if they are not already present.

You do not need to pre-install these tools manually before running Solo.

The only hard requirement before you begin is a container runtime - either Docker Desktop or Podman. Solo cannot install a container runtime on your behalf.

Docker

Solo requires Docker Desktop (macOS, Windows) or Docker Engine / Podman (Linux) with the following minimum resource allocation:

• Memory: at least 12 GB allocated to Docker.
• CPU: at least 6 cores allocated to Docker.

Configure Docker Desktop Resources

To allocate the required resources in Docker Desktop:

1. Open Docker Desktop.

2. Go to Settings > Resources > Memory and set it to at least 12 GB.

3. Go to Settings > Resources > CPU and set it to at least 6 cores.

4. Click Apply & Restart.

Note: If Docker Desktop does not have enough memory or CPU allocated, the one-shot deployment will fail or produce unhealthy pods.

Platform Setup

Solo supports macOS, Linux, and Windows via WSL2. Select your platform below to install the required container runtime and configure your environment, before proceeding to Quickstart:

• macOS
• Linux
• Windows (WSL2)

Alternative Installation: npm (for contributors and advanced users)

If you need more control over dependencies or are contributing to Solo development, you can install Solo via npm instead of Homebrew.

Note: Node.js >= 22.0.0 and Kind must be installed separately before using this method.

npm install -g @hashgraph/solo

Optional Tools

The following tools are not required but are recommended for monitoring and managing your local network:

• k9s (>= v0.27.4): A terminal-based UI for managing Kubernetes clusters. Install it with:

  brew install k9s
  

  Run k9s to launch the cluster viewer.

Version Compatibility Reference

The table below shows the full compatibility matrix for the current and recent Solo releases:

For a list of legacy releases, see the legacy versions documentation.

Troubleshooting Installation

If you experience issues installing or upgrading Solo (for example, conflicts with a previous installation), you may need to clean up your environment first.

Warning: The commands below will delete Solo-managed Kind clusters and remove your Solo home directory (~/.solo).

# Delete only Solo-managed Kind clusters (names starting with "solo")
kind get clusters | grep '^solo' | while read cluster; do
  kind delete cluster -n "$cluster"
done

# Remove Solo configuration and cache
rm -rf ~/.solo

After cleaning up, retry the installation with:

brew install hiero-ledger/tools/solo

1.2 - Quickstart

Overview

Solo Quickstart provides a single, one-shot command path to deploy a running Hiero test network using the Solo CLI tool. This guide covers installing Solo, running the one-shot deployment, verifying the network, and accessing local service endpoints.

Note: This guide assumes basic familiarity with command-line interfaces and Docker.

Prerequisites

Before you begin, ensure you have completed the following:

• System Readiness:
  • Prepare your local environment (Docker, Kind, Kubernetes, and related tooling) by following the System Readiness guide.

Note: Quickstart only covers what you need to run solo one-shot single deploy and verify that the network is working. Detailed version requirements, OS-specific notes, and optional tools are documented in System Readiness.

Install Solo CLI

Install the latest Solo CLI globally using one of the following methods:

• Homebrew (recommended for macOS/Linux/WSL2):

  brew install hiero-ledger/tools/solo
  

• npm (alternatively, install Solo via npm):

  npm install -g @hashgraph/solo@latest
  

Verify the installation

Confirm that Solo is installed and available on your PATH:

solo --version

Expected output (version may be different):

** Solo **
Version : 0.59.1
**

If you see a similar banner with a valid Solo version (for example, 0.59.1), your installation is successful.

Deploy a local network (one-shot)

Use the one-shot command to create and configure a fully functional local Hiero network:

solo one-shot single deploy

This command performs the following actions:

• Creates or connects to a local Kubernetes cluster using Kind.
• Deploys the Solo network components.
• Sets up and funds default test accounts.
• Exposes gRPC and JSON-RPC endpoints for client access.

What gets deployed

solo one-shot multiple deploy --num-consensus-nodes 3

solo one-shot multiple destroy

Verify the network

After the one-shot deployment completes, verify that the Kubernetes workloads are healthy.

You can monitor the Kubernetes workloads with standard tools:

kubectl get pods -A | grep -v kube-system

Confirm that all Solo-related pods are in a Running or Completed state.

Tip: The Solo testing team recommends k9s for managing Kubernetes clusters. It provides a terminal-based UI that makes it easy to view pods, logs, and cluster status. Install it with brew install k9s and run k9s to launch.

Access your local network

After the one-shot deployment completes and all pods are running, your local services are available at the following endpoints:

1.3 - Managing Your Network

Overview

This guide covers day-to-day management operations for a running Solo network, including starting, stopping, and restarting nodes, capturing logs, and upgrading the network.

Prerequisites

Before proceeding, ensure you have completed the following:

• System Readiness - your local environment meets all hardware and software requirements.
• Quickstart - you have a running Solo network deployed using solo one-shot single deploy.

Find Your Deployment Name

Most management commands require your deployment name. Run the following command to retrieve it:

cat ~/.solo/cache/last-one-shot-deployment.txt

Expected output:

solo-deployment-<hash>

Use the value returned from this command as <deployment-name> in all commands on this page.

Stopping and Starting Nodes

Stop all nodes

Use this command to pause all consensus nodes without destroying the deployment:

solo consensus node stop --deployment <deployment-name>

Start nodes

Use this command to bring stopped nodes back online:

solo consensus node start --deployment <deployment-name>

Restart nodes

Use this command to stop and start all nodes in a single operation:

solo consensus node restart --deployment <deployment-name>

To verify pod status after any of the above commands, see Verify the network in the Quickstart guide.

Viewing Logs

To capture logs and diagnostic information for your deployment:

solo deployment diagnostics all --deployment <deployment-name>

Logs are saved to ~/.solo/logs/.

Expected output:

******************************* Solo *********************************************
Version : 0.59.1
Kubernetes Context : kind-solo
Kubernetes Cluster : kind-solo
Current Command : deployment diagnostics all --deployment <deployment-name>
**********************************************************************************

✔ Initialize [0.3s]
✔ Get consensus node logs and configs [15s]
✔ Get Helm chart values from all releases [2s]
✔ Downloaded logs from 10 Hiero component pods [1s]
✔ Get node states [10s]

Configurations and logs saved to /Users/<username>/.solo/logs
Log zip file network-node1-0-log-config.zip downloaded to /Users/<username>/.solo/logs/<deployment-name>
Helm chart values saved to /Users/<username>/.solo/logs/helm-chart-values

You can also retrieve logs for a specific pod directly using kubectl:

kubectl logs -n <namespace> <pod-name>

Replace and with the values from your deployment. You can find the available pods and namespaces by running:

kubectl get pods -A | grep -v kube-system

Updating the Network

To update your consensus nodes to a new Hiero version:

solo consensus network upgrade --deployment <deployment-name> --upgrade-version <version>

Replace with the target Hiero version, for example v0.59.0.

Note: Check the Version Compatibility Reference in the System Readiness guide to confirm the Hiero version supported by your current Solo release before upgrading.

1.4 - Cleanup

Overview

This guide covers how to tear down a Solo network deployment, understand resource usage, and perform a full reset when needed.

Prerequisites

Before proceeding, ensure you have completed the following:

• Quickstart — you have a running Solo network deployed using solo one-shot single deploy.

Destroying Your Network

Important: Always destroy your network before deploying a new one to avoid conflicts and errors.

To remove your Solo network:

solo one-shot single destroy

This command performs the following actions:

• Removes all deployed pods and services in the Solo namespace..
• Cleans up the Kubernetes namespace, which also removes associated PVCs when namespace deletion completes successfully.
• Deletes the Kind cluster.
• Updates Solo’s internal state.

Note: solo one-shot single destroy does not delete the underlying Kind cluster. If you created a Solo network on a local Kind cluster, the cluster remains until you delete it manually.

Failure modes and rerunning destroy

If solo one-shot single destroy fails part-way through (for example, due to an earlier deploy error), some resources may remain:

• The Solo namespace or one or more PVCs may not be deleted, which can leave Docker volumes appearing as “in use”.
• The destroy commands are designed to be idempotent, so you can safely rerun solo one-shot single destroy to complete cleanup.

If rerunning destroy does not release the resources, use the Full Reset procedure below to force a clean state.

Resource Usage

Solo deploys a fully functioning mirror node that stores the transaction history generated by your local test network. During active testing, the mirror node’s resource consumption will grow as it processes more transactions. If you notice increasing resource usage, destroy and redeploy the network to reset it to a clean state.

Full Reset

Warning: This is a last resort procedure. Only use the Full Reset if solo one-shot single destroy fails or your Solo state is corrupted. For normal teardown, always use solo one-shot single destroy instead.

# Delete only Solo-managed Kind clusters (names starting with "solo")
kind get clusters | grep '^solo' | while read cluster; do
  kind delete cluster -n "$cluster"
done

# Remove Solo configuration and cache
rm -rf ~/.solo

Warning: The commands above will delete all Solo-managed Kind clusters and remove your Solo home directory (~/.solo). Always use the grep '^solo' filter when listing clusters - omitting it will delete every Kind cluster on your machine, including any unrelated to Solo.

After deleting the Kind cluster, Kubernetes resources (including namespaces and PVCs) and their associated volumes should be released. If Docker still reports unused volumes that you want to remove, you can optionally run:

# Optional: remove all unused Docker volumes
docker volume prune

Warning: docker volume prune removes all unused Docker volumes on your machine, not just those created by Solo. Only run this command if you understand its impact.

• To redeploy after a full reset, follow the Quickstart guide.

2 - Advanced Solo Setup

2.1 - Using Environment Variables

Overview

Solo supports a set of environment variables that let you customize its behaviour without modifying command-line flags on every run. Variables set in your shell environment take effect automatically for all subsequent Solo commands.

Tip: Add frequently used variables to your shell profile (e.g. ~/.zshrc or ~/.bashrc) to persist them across sessions.

General

Network and Node Identity

Operator and Key Configuration

Note: Full key values are omitted above for readability. Refer to the source defaults for complete key strings.

Node Client Behaviour

Pod and Network Readiness

Block Node

Relay Node

Load Balancer

Lease Management

Component Versions

Helm Chart URLs

Network Load Generator

One-Shot Deployment

2.2 - Network Deployments

2.2.1 - One-shot Falcon Deployment

Overview

One-shot Falcon deployment is Solo’s YAML-driven one-shot workflow. It uses the same core deployment pipeline as solo one-shot single deploy, but lets you inject component-specific flags through a single values file.

One-shot use Falcon deployment when you need a repeatable advanced setup, want to check a complete deployment into source control, or need to customise component flags without running every Solo command manually.

Falcon is especially useful for:

• CI/CD pipelines and automated test environments.
• Reproducible local developer setups.
• Advanced deployments that need custom chart paths, image versions, ingress, storage, TLS, or node startup options.

Important: Falcon is an orchestration layer over Solo’s standard commands. It does not introduce a separate deployment model. Solo still creates a deployment, attaches clusters, deploys the network, configures nodes, and then adds optional components such as mirror node, explorer, and relay.

Prerequisites

Before proceeding, ensure you have completed the following:

• System Readiness -your local environment meets the hardware and software requirements for Solo, Kubernetes, Docker, Kind, kubectl, and Helm.

• Quickstart -you are already familiar with the standard one-shot deployment workflow.

• Set your environment variables if you have not already done so:

  export SOLO_CLUSTER_NAME=solo
  export SOLO_NAMESPACE=solo
  export SOLO_CLUSTER_SETUP_NAMESPACE=solo-cluster
  export SOLO_DEPLOYMENT=solo-deployment
  

How Falcon Works

When you run Falcon deployment, Solo executes the same end-to-end deployment sequence used by its one-shot workflows:

1. Connect to the Kubernetes cluster.
2. Create a deployment and attach the cluster reference.
3. Set up shared cluster components.
4. Generate gossip and TLS keys.
5. Deploy the consensus network and, if enabled, the block node (in parallel).
6. Set up and start consensus nodes.
7. Optionally, deploy mirror node, explorer, and relay in parallel for faster startup.
8. Create predefined test accounts.
9. Write deployment notes, versions, port-forward details, and account data to a local output directory.

The difference is that Falcon reads a YAML file and maps its top-level sections to the underlying Solo subcommands.

For the full list of supported CLI flags per section, see the Falcon Values File Reference.

Create a Falcon Values File

Create a YAML file to control every component of your Solo deployment. The file can have any name -falcon-values.yaml is used throughout this guide as a convention.

Note: Keys within each section must be the full CLI flag name including the -- prefix - for example, --release-tag, not release-tag or -r. Any section you omit from the file is skipped, and Solo uses the built-in defaults for that component.

Example: Single-Node Falcon Deployment

The following falcon-values.yaml example deploys a standard single-node network with mirror node, explorer, and relay enabled:

network:
  --release-tag: "v0.71.0"
  --pvcs: false

setup:
  --release-tag: "v0.71.0"

consensusNode:
  --force-port-forward: true

mirrorNode:
  --enable-ingress: true
  --pinger: true
  --force-port-forward: true

explorerNode:
  --enable-ingress: true
  --force-port-forward: true

relayNode:
  --node-aliases: "node1"
  --force-port-forward: true

Deploy with Falcon one-shot

Run Falcon deployment by pointing Solo at the values file:

solo one-shot falcon deploy --values-file falcon-values.yaml

Solo creates a one-shot deployment, applies the values from the YAML file to the appropriate subcommands, and then deploys the full environment.

What Falcon Does Not Read from the File

Some Falcon settings are controlled directly by the top-level command flags, not by section entries in the values file:

• --values-file selects the YAML file to load.
• --deploy-mirror-node, --deploy-explorer, and --deploy-relay control whether those optional components are deployed at all.
• --deployment, --namespace, --cluster-ref, and --num-consensus-nodes are top-level one-shot inputs.

Important: Do not rely on --deployment inside falcon-values.yaml. Solo intentionally ignores --deployment values from section content during Falcon argument expansion. Set the deployment name on the command line if you need a specific name.

Tip: When not specified, Falcon uses these defaults: --deployment one-shot, --namespace one-shot, --cluster-ref one-shot, and --num-consensus-nodes 1. Pass any of these explicitly on the command line to override them.

Example:

solo one-shot falcon deploy \
  --deployment falcon-demo \
  --cluster-ref one-shot \
  --values-file falcon-values.yaml

Multi-Node Falcon Deployment

For multiple consensus nodes, set the node count on the Falcon command and then provide matching per-node settings where required.

• Example:

  solo one-shot falcon deploy \
    --deployment falcon-multi \
    --num-consensus-nodes 3 \
    --values-file falcon-values.yaml
  

• Example multi-node values file:

  network:
    --release-tag: "v0.71.0"
    --pvcs: true
  
  setup:
    --release-tag: "v0.71.0"
  
  consensusNode:
    --force-port-forward: true
    --stake-amounts: "100,100,100"
  
  mirrorNode:
    --enable-ingress: true
    --pinger: true
  
  explorerNode:
    --enable-ingress: true
  
  relayNode:
    --node-aliases: "node1,node2,node3"
  

• The --node-aliases value in the relayNode section must match the node aliases generated by --num-consensus-nodes. Nodes are auto-named node1, node2, node3, and so on. Setting this to only node1 is valid if you want the relay to serve a single node, but specifying all aliases is typical for full coverage.

• Use this pattern when you need a repeatable multi-node deployment but do not want to manage each step manually.

Note: Multi-node deployments require more host resources than single-node deployments. Follow the resource guidance in System Readiness, and increase Docker memory and CPU allocation before deploying.

(Optional) Component Toggles

Falcon can skip optional components at the command line without requiring a second YAML file.

For example, to deploy only the consensus network and mirror node:

solo one-shot falcon deploy \
  --values-file falcon-values.yaml \
  --deploy-explorer=false \
  --deploy-relay=false

Available toggles and their defaults:

Important: The explorer and relay both depend on the mirror node. Setting --deploy-mirror-node=false while keeping --deploy-explorer=true or --deploy-relay=true is not a supported configuration and will result in a failed deployment.

This is useful when you want to:

• Reduce resource usage in CI jobs.
• Isolate one component during testing.
• Reuse the same YAML file across multiple deployment profiles.

Common Falcon Customisations

Because each YAML section maps directly to the corresponding Solo subcommand, you can use Falcon to centralise advanced options such as:

• Custom release tags for the consensus node platform.
• Local chart directories for mirror node, relay, explorer, or block node.
• Local consensus node build paths for development workflows.
• Ingress and domain settings.
• Mirror node external database settings.
• Node startup settings such as state files, port forwarding, and stake amounts.
• Storage backends and credentials for stream file handling.

Example: Local Development with Local Chart Directories

setup:
  --local-build-path: "/path/to/hiero-consensus-node/hedera-node/data"

mirrorNode:
  --mirror-node-chart-dir: "/path/to/hiero-mirror-node/charts"

relayNode:
  --relay-chart-dir: "/path/to/hiero-json-rpc-relay/charts"

explorerNode:
  --explorer-chart-dir: "/path/to/hiero-mirror-node-explorer/charts"

This pattern is useful for local integration testing against unpublished component builds.

Falcon with Block Node

Falcon can also include block node configuration.

Note: Block node workflows are advanced and require higher resource allocation and version compatibility across consensus node, block node, and related components. Docker memory must be set to at least 16 GB before deploying with block node enabled.

Block node support also requires the ONE_SHOT_WITH_BLOCK_NODE=true environment variable to be set before running falcon deploy. Without it, Solo skips the block node add step even if a blockNode section is present in the values file.

Block node deployment is subject to version compatibility requirements. Minimum versions are consensus node ≥ v0.72.0 and block node ≥ 0.29.0. Mixing incompatible versions will cause the deployment to fail. Check the Version Compatibility Reference before enabling block node.

Example:

network:
  --release-tag: "v0.72.0"

setup:
  --release-tag: "v0.72.0"

consensusNode:
  --force-port-forward: true

blockNode:
  --release-tag: "v0.29.0"
  --enable-ingress: false

mirrorNode:
  --enable-ingress: true
  --pinger: true

explorerNode:
  --enable-ingress: true

relayNode:
  --node-aliases: "node1"
  --force-port-forward: true

Use block node settings only when your target Solo and component versions are known to be compatible.

Rollback and Failure Behaviour

Falcon deployment enables automatic rollback by default.

If deployment fails after resources have already been created, Solo attempts to destroy the one-shot deployment automatically and clean up the namespace.

If you want to preserve the failed deployment for debugging, disable rollback:

solo one-shot falcon deploy \
  --values-file falcon-values.yaml \
  --no-rollback

Use --no-rollback only when you explicitly want to inspect partial resources, logs, or Kubernetes objects after a failed run.

Deployment Output

After a successful Falcon deployment, Solo writes deployment metadata to ~/.solo/one-shot-<deployment>/ where <deployment> is the value of the --deployment flag (default: one-shot).

This directory typically contains:

• notes - human-readable deployment summary
• versions - component versions recorded at deploy time
• forwards - port-forward configuration
• accounts.json - predefined test account keys and IDs. All accounts are ECDSA Alias accounts (EVM-compatible) and include a publicAddress field. The file also includes the system operator account.

This makes Falcon especially useful for automation, because the deployment artifacts are written to a predictable path after each run.

To inspect the latest one-shot deployment metadata later, run:

solo one-shot show deployment

If port-forwards are interrupted after deployment - for example after a system restart or network disruption - restore them without redeploying:

solo deployment refresh port-forwards

Destroy a Falcon Deployment

• Destroy the Falcon deployment with:

  solo one-shot falcon destroy
  

• Solo removes deployed extensions first, then destroys the mirror node, network, cluster references, and local deployment metadata.

• If multiple deployments exist locally, Solo prompts you to choose which one to destroy unless you pass --deployment explicitly.

  solo one-shot falcon destroy --deployment falcon-demo
  

When to Use Falcon vs. Manual Deployment

Use Falcon deployment when you want a single, repeatable command backed by a versioned YAML file.

Use Step-by-Step Manual Deployment when you need to pause between steps, inspect intermediate state, or debug a specific deployment phase in isolation.

In practice:

• Falcon is better for automation and repeatability.
• Manual deployment is better for debugging and low-level control.

Reference

• Falcon Values File Reference - full list of supported CLI flags, types, and defaults for every section.
• Upstream example values file - working reference from the Solo repository.

Tip: If you are creating a values file for the first time, start from the annotated template in the Solo repository rather than writing one from scratch:

examples/one-shot-falcon/falcon-values.yaml

This file includes all supported sections and flags with inline comments explaining each option. Copy it, remove what you do not need, and adjust the values for your environment.

2.2.2 - Falcon Values File Reference

Overview

This page catalogs the Solo CLI flags accepted under each top-level section of a Falcon values file. Each entry corresponds to the command-line flag that the underlying Solo subcommand accepts.

Sections map to subcommands as follows:

All flag names must be written in long form with double dashes (for example, --release-tag). Flags left empty ("") or matching their default value are ignored by Solo at argument expansion time.

Note: Not every flag listed here is relevant to every deployment. Use this page as a lookup when writing or debugging a values file. For a working example file, see the upstream reference at https://github.com/hiero-ledger/solo/tree/main/examples/one-shot-falcon.

Consensus Network Deploy — network

Flags passed to solo consensus network deploy.

Consensus Node Setup — setup

Flags passed to solo consensus node setup.

Consensus Node Start — consensusNode

Flags passed to solo consensus node start.

Mirror Node Add — mirrorNode

Flags passed to solo mirror node add.

Explorer Add — explorerNode

Flags passed to solo explorer node add.

JSON-RPC Relay Add — relayNode

Flags passed to solo relay node add.

Block Node Add — blockNode

Flags passed to solo block node add.

Important: The blockNode section is only read when ONE_SHOT_WITH_BLOCK_NODE=true is set in the environment. Otherwise Solo skips the block node add step regardless of whether a blockNode section is present. Version requirements: Consensus node ≥ v0.72.0 and block node ≥ 0.29.0. Use --force to bypass version gating during testing.

Top-Level Falcon Command Flags

The following flags are passed directly on the solo one-shot falcon deploy command line. They are not read from the values file sections.

2.2.3 - Step-by-Step Manual Deployment

Overview

Manual deployment lets you deploy each Solo network component individually, giving you full control over configuration, sequencing, and troubleshooting. Use this approach when you need to customise specific steps, debug a component in isolation, or integrate Solo into a bespoke automation pipeline.

Prerequisites

Before proceeding, ensure you have completed the following:

• System Readiness — your local environment meets all hardware and software requirements (Docker, kind, kubectl, helm, Solo).

• Quickstart — you have a running Kind cluster and have run solo init at least once.

• Set your environment variables if you have not already done so:

  export SOLO_CLUSTER_NAME=solo
  export SOLO_NAMESPACE=solo
  export SOLO_CLUSTER_SETUP_NAMESPACE=solo-cluster
  export SOLO_DEPLOYMENT=solo-deployment
  

Deployment Steps

1. Connect Cluster and Create Deployment

• Connect Solo to the Kind cluster and create a new deployment configuration:

  # Connect to the Kind cluster
  solo cluster-ref config connect \
    --cluster-ref kind-${SOLO_CLUSTER_NAME} \
    --context kind-${SOLO_CLUSTER_NAME}
  
  # Create a new deployment
  solo deployment config create \
    -n "${SOLO_NAMESPACE}" \
    --deployment "${SOLO_DEPLOYMENT}"
  

• Expected Output:

  ******************************* Solo *********************************************
  Version   : 0.63.0
  Kubernetes Context : kind-solo
  Kubernetes Cluster : kind-solo
  Current Command  : cluster-ref config connect --cluster-ref kind-solo --context kind-solo
  **********************************************************************************
  Initialize
  ✔ Initialize 
  Validating cluster ref: 
  ✔ Validating cluster ref: kind-solo 
  Test connection to cluster: 
  ✔ Test connection to cluster: kind-solo 
  Associate a context with a cluster reference: 
  ✔ Associate a context with a cluster reference: kind-solo
  

2. Add Cluster to Deployment

• Attach the cluster to your deployment and specify the number of consensus nodes:

  1. Single node:

  solo deployment cluster attach \
    --deployment "${SOLO_DEPLOYMENT}" \
    --cluster-ref kind-${SOLO_CLUSTER_NAME} \
    --num-consensus-nodes 1
  

  2. Multiple nodes (e.g., –num-consensus-nodes 3):

  solo deployment cluster attach \
    --deployment "${SOLO_DEPLOYMENT}" \
    --cluster-ref kind-${SOLO_CLUSTER_NAME} \
    --num-consensus-nodes 3
  

• Expected Output:

  solo-deployment_ADD_CLUSTER_OUTPUT
  

3. Generate Keys

• Generate the gossip and TLS keys for your consensus nodes:

  solo keys consensus generate \
    --gossip-keys \
    --tls-keys \
    --deployment "${SOLO_DEPLOYMENT}"
  

  PEM key files are written to ~/.solo/cache/keys/.

• Example output:

  ******************************* Solo *********************************************
  Version   : 0.63.0
  Kubernetes Context : kind-solo
  Kubernetes Cluster : kind-solo
  Current Command  : keys consensus generate --gossip-keys --tls-keys --deployment solo-deployment
  **********************************************************************************
  Initialize
  ✔ Initialize 
  Generate gossip keys
  Backup old files
  ✔ Backup old files 
  Gossip key for node: node1
  ✔ Gossip key for node: node1 [0.2s]
  ✔ Generate gossip keys [0.2s]
  Generate gRPC TLS Keys
  Backup old files
  TLS key for node: node1
  ✔ Backup old files 
  ✔ TLS key for node: node1 [0.3s]
  ✔ Generate gRPC TLS Keys [0.3s]
  Finalize
  ✔ Finalize
  

4. Set Up Cluster with Shared Components

• Install shared cluster-level components (MinIO Operator, Prometheus CRDs, etc.) into the cluster setup namespace:

  solo cluster-ref config setup --cluster-setup-namespace "${SOLO_CLUSTER_SETUP_NAMESPACE}"
  

• Example output:

  ******************************* Solo *********************************************
  Version   : 0.63.0
  Kubernetes Context : kind-solo
  Kubernetes Cluster : kind-solo
  Current Command  : cluster-ref config setup --cluster-setup-namespace solo-cluster
  **********************************************************************************
  Check dependencies
  Check dependency: helm [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  Check dependency: kind [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  Check dependency: kubectl [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  ✔ Check dependency: kind [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependency: helm [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependency: kubectl [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependencies 
  Setup chart manager
  ✔ Setup chart manager [0.6s]
  Initialize
  ✔ Initialize 
  Install cluster charts
  Install pod-monitor-role ClusterRole
  -  ClusterRole pod-monitor-role already exists in context kind-solo, skipping
  ✔ Install pod-monitor-role ClusterRole 
  Install MinIO Operator chart
  ✔ MinIO Operator chart installed successfully on context kind-solo
  ✔ Install MinIO Operator chart [0.8s]
  ✔ Install cluster charts [0.8s]
  

5. Deploy the Network

• Deploy the Solo network Helm chart, which provisions the consensus node pods, HAProxy, Envoy, and MinIO:

  solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}"
  

• Example output:

  ******************************* Solo *********************************************
  Version   : 0.63.0
  Kubernetes Context : kind-solo
  Kubernetes Cluster : kind-solo
  Current Command  : consensus network deploy --deployment solo-deployment --release-tag v0.66.0
  **********************************************************************************
  Check dependencies
  Check dependency: helm [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  Check dependency: kind [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  Check dependency: kubectl [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  ✔ Check dependency: kind [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependency: helm [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependency: kubectl [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependencies 
  Setup chart manager
  ✔ Setup chart manager [0.7s]
  Initialize
  Acquire lock
  ✔ Acquire lock - lock acquired successfully, attempt: 1/10 
  ✔ Initialize [0.2s]
  Copy gRPC TLS Certificates
  Copy gRPC TLS Certificates [SKIPPED: Copy gRPC TLS Certificates]
  Prepare staging directory
  Copy Gossip keys to staging
  ✔ Copy Gossip keys to staging 
  Copy gRPC TLS keys to staging
  ✔ Copy gRPC TLS keys to staging 
  ✔ Prepare staging directory 
  Copy node keys to secrets
  Copy TLS keys
  Node: node1, cluster: kind-solo
  Copy Gossip keys
  ✔ Copy TLS keys 
  ✔ Copy Gossip keys 
  ✔ Node: node1, cluster: kind-solo 
  ✔ Copy node keys to secrets 
  Install monitoring CRDs
  Pod Logs CRDs
  ✔ Pod Logs CRDs 
  Prometheus Operator CRDs
  - Installed prometheus-operator-crds chart, version: 24.0.2
  ✔ Prometheus Operator CRDs [4s]
  ✔ Install monitoring CRDs [4s]
  Install chart 'solo-deployment'
  - Installed solo-deployment chart, version: 0.62.0
  ✔ Install chart 'solo-deployment' [2s]
  Check for load balancer
  Check for load balancer [SKIPPED: Check for load balancer]
  Redeploy chart with external IP address config
  Redeploy chart with external IP address config [SKIPPED: Redeploy chart with external IP address config]
  Check node pods are running
  Check Node: node1, Cluster: kind-solo
  ✔ Check Node: node1, Cluster: kind-solo [24s]
  ✔ Check node pods are running [24s]
  Check proxy pods are running
  Check HAProxy for: node1, cluster: kind-solo
  Check Envoy Proxy for: node1, cluster: kind-solo
  ✔ Check HAProxy for: node1, cluster: kind-solo 
  ✔ Check Envoy Proxy for: node1, cluster: kind-solo 
  ✔ Check proxy pods are running 
  Check auxiliary pods are ready
  Check MinIO
  ✔ Check MinIO 
  ✔ Check auxiliary pods are ready 
  Add node and proxies to remote config
  ✔ Add node and proxies to remote config 
  Copy wraps lib into consensus node
  Copy wraps lib into consensus node [SKIPPED: Copy wraps lib into consensus node]
  Copy block-nodes.json
  ✔ Copy block-nodes.json [1s]
  Copy JFR config file to nodes
  Copy JFR config file to nodes [SKIPPED: Copy JFR config file to nodes]
  

6. Set Up Consensus Nodes

• Download the consensus node platform software and configure each node:

  export CONSENSUS_NODE_VERSION=v0.66.0
  
  solo consensus node setup \
    --deployment "${SOLO_DEPLOYMENT}" \
    --release-tag "${CONSENSUS_NODE_VERSION}"
  

• Example output:

  ******************************* Solo *********************************************
  Version   : 0.63.0
  Kubernetes Context : kind-solo
  Kubernetes Cluster : kind-solo
  Current Command  : consensus node setup --deployment solo-deployment --release-tag v0.66.0
  **********************************************************************************
  Load configuration
  ✔ Load configuration [0.2s]
  Initialize
  ✔ Initialize [0.2s]
  Validate nodes states
  Validating state for node node1
  ✔ Validating state for node node1 - valid state: requested 
  ✔ Validate nodes states 
  Identify network pods
  Check network pod: node1
  ✔ Check network pod: node1 
  ✔ Identify network pods 
  Fetch platform software into network nodes
  Update node: node1 [ platformVersion = v0.66.0, context = kind-solo ]
  ✔ Update node: node1 [ platformVersion = v0.66.0, context = kind-solo ] [3s]
  ✔ Fetch platform software into network nodes [3s]
  Setup network nodes
  Node: node1
  Copy configuration files
  ✔ Copy configuration files [0.3s]
  Set file permissions
  ✔ Set file permissions [0.4s]
  ✔ Node: node1 [0.8s]
  ✔ Setup network nodes [0.9s]
  setup network node folders
  ✔ setup network node folders [0.1s]
  Change node state to configured in remote config
  ✔ Change node state to configured in remote config
  

7. Start Consensus Nodes

• Start all configured nodes and wait for them to reach ACTIVE status:

  solo consensus node start --deployment "${SOLO_DEPLOYMENT}"
  

• Example output:

  ******************************* Solo *********************************************
  Version   : 0.63.0
  Kubernetes Context : kind-solo
  Kubernetes Cluster : kind-solo
  Current Command  : consensus node start --deployment solo-deployment
  **********************************************************************************
  Check dependencies
  Check dependency: helm [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  Check dependency: kind [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  Check dependency: kubectl [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  ✔ Check dependency: kind [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependency: helm [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependency: kubectl [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependencies 
  Setup chart manager
  ✔ Setup chart manager [0.7s]
  Load configuration
  ✔ Load configuration [0.2s]
  Initialize
  ✔ Initialize [0.2s]
  Validate nodes states
  Validating state for node node1
  ✔ Validating state for node node1 - valid state: configured 
  ✔ Validate nodes states 
  Identify existing network nodes
  Check network pod: node1
  ✔ Check network pod: node1 
  ✔ Identify existing network nodes 
  Upload state files network nodes
  Upload state files network nodes [SKIPPED: Upload state files network nodes]
  Starting nodes
  Start node: node1
  ✔ Start node: node1 [0.1s]
  ✔ Starting nodes [0.1s]
  Enable port forwarding for debug port and/or GRPC port
  Using requested port 50211
  ✔ Enable port forwarding for debug port and/or GRPC port 
  Check all nodes are ACTIVE
  Check network pod: node1 
  ✔ Check network pod: node1  - status ACTIVE, attempt: 16/300 [20s]
  ✔ Check all nodes are ACTIVE [20s]
  Check node proxies are ACTIVE
  Check proxy for node: node1
  ✔ Check proxy for node: node1 [6s]
  ✔ Check node proxies are ACTIVE [6s]
  Wait for TSS
  Wait for TSS [SKIPPED: Wait for TSS]
  set gRPC Web endpoint
  Using requested port 30212
  ✔ set gRPC Web endpoint [3s]
  Change node state to started in remote config
  ✔ Change node state to started in remote config 
  Add node stakes
  Adding stake for node: node1
  ✔ Adding stake for node: node1 [4s]
  ✔ Add node stakes [4s]
  Stopping port-forward for port [30212]
  

8. Deploy Mirror Node

• Deploy the Hedera Mirror Node, which indexes all transaction data and exposes a REST API and gRPC endpoint:

  solo mirror node add \
    --deployment "${SOLO_DEPLOYMENT}" \
    --cluster-ref kind-${SOLO_CLUSTER_NAME} \
    --enable-ingress \
    --pinger
  

  The --pinger flag keeps the mirror node’s importer active by regularly submitting record files. The --enable-ingress flag installs the HAProxy ingress controller for the mirror node REST API.

• Example output:

  ******************************* Solo *********************************************
  Version   : 0.63.0
  Kubernetes Context : kind-solo
  Kubernetes Cluster : kind-solo
  Current Command  : mirror node add --deployment solo-deployment --cluster-ref kind-solo --enable-ingress --quiet-mode
  **********************************************************************************
  Check dependencies
  Check dependency: helm [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  Check dependency: kind [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  Check dependency: kubectl [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  ✔ Check dependency: kind [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependency: helm [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependency: kubectl [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependencies 
  Setup chart manager
  ✔ Setup chart manager [0.6s]
  Initialize
  Using requested port 30212
  Acquire lock
  ✔ Acquire lock - lock acquired successfully, attempt: 1/10 [0.1s]
  ✔ Initialize [1s]
  Enable mirror-node
  Prepare address book
  ✔ Prepare address book 
  Install mirror ingress controller
  - Installed haproxy-ingress-1 chart, version: 0.14.5
  ✔ Install mirror ingress controller [0.7s]
  Deploy mirror-node
  - Installed mirror chart, version: v0.149.0
  ✔ Deploy mirror-node [3s]
  ✔ Enable mirror-node [4s]
  Check pods are ready
  Check Postgres DB
  Check REST API
  Check GRPC
  Check Monitor
  Check Web3
  Check Importer
  ✔ Check Postgres DB [32s]
  ✔ Check Web3 [46s]
  ✔ Check REST API [52s]
  ✔ Check GRPC [58s]
  ✔ Check Monitor [1m16s]
  ✔ Check Importer [1m32s]
  ✔ Check pods are ready [1m32s]
  Seed DB data
  Insert data in public.file_data
  ✔ Insert data in public.file_data [0.6s]
  ✔ Seed DB data [0.6s]
  Add mirror node to remote config
  ✔ Add mirror node to remote config 
  Enable port forwarding for mirror ingress controller
  Using requested port 8081
  ✔ Enable port forwarding for mirror ingress controller 
  Stopping port-forward for port [30212]
  

9. Deploy Explorer

• Deploy the Hiero Explorer, a web UI for browsing transactions and accounts:

  solo explorer node add \
    --deployment "${SOLO_DEPLOYMENT}" \
    --cluster-ref kind-${SOLO_CLUSTER_NAME}
  

• Example output:

  ******************************* Solo *********************************************
  Version   : 0.63.0
  Kubernetes Context : kind-solo
  Kubernetes Cluster : kind-solo
  Current Command  : explorer node add --deployment solo-deployment --cluster-ref kind-solo --quiet-mode
  **********************************************************************************
  Check dependencies
  Check dependency: helm [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  Check dependency: kind [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  Check dependency: kubectl [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  ✔ Check dependency: kind [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependency: helm [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependency: kubectl [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependencies 
  Setup chart manager
  ✔ Setup chart manager [0.7s]
  Initialize
  Acquire lock
  ✔ Acquire lock - lock acquired successfully, attempt: 1/10 
  ✔ Initialize [0.5s]
  Load remote config
  ✔ Load remote config [0.2s]
  Install cert manager
  Install cert manager [SKIPPED: Install cert manager]
  Install explorer
  - Installed hiero-explorer-1 chart, version: 26.0.0
  ✔ Install explorer [0.8s]
  Install explorer ingress controller
  Install explorer ingress controller [SKIPPED: Install explorer ingress controller]
  Check explorer pod is ready
  ✔ Check explorer pod is ready [18s]
  Check haproxy ingress controller pod is ready
  Check haproxy ingress controller pod is ready [SKIPPED: Check haproxy ingress controller pod is ready]
  Add explorer to remote config
  ✔ Add explorer to remote config 
  Enable port forwarding for explorer
  No port forward config found for Explorer
  Using requested port 8080
  ✔ Enable port forwarding for explorer [0.1s]
  

10. Deploy JSON-RPC Relay

• Deploy the Hiero JSON-RPC Relay to expose an Ethereum-compatible JSON-RPC endpoint for EVM tooling (MetaMask, Hardhat, Foundry, etc.):

  solo relay node add \
    -i node1 \
    --deployment "${SOLO_DEPLOYMENT}"
  

• Example output:

  ******************************* Solo *********************************************
  Version   : 0.63.0
  Kubernetes Context : kind-solo
  Kubernetes Cluster : kind-solo
  Current Command  : relay node add --node-aliases node1 --deployment solo-deployment --cluster-ref kind-solo
  **********************************************************************************
  Check dependencies
  Check dependency: helm [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  Check dependency: kind [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  Check dependency: kubectl [OS: linux, Release: 6.8.0-106-generic, Arch: x64]
  ✔ Check dependency: kind [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependency: helm [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependency: kubectl [OS: linux, Release: 6.8.0-106-generic, Arch: x64] 
  ✔ Check dependencies 
  Setup chart manager
  ✔ Setup chart manager [0.7s]
  Initialize
  Acquire lock
  ✔ Acquire lock - lock acquired successfully, attempt: 1/10 
  ✔ Initialize [0.4s]
  Check chart is installed
  ✔ Check chart is installed [0.1s]
  Prepare chart values
  Using requested port 30212
  ✔ Prepare chart values [1s]
  Deploy JSON RPC Relay
  - Installed relay-1 chart, version: 0.73.0
  ✔ Deploy JSON RPC Relay [0.7s]
  Check relay is running
  ✔ Check relay is running [16s]
  Check relay is ready
  ✔ Check relay is ready [21s]
  Add relay component in remote config
  ✔ Add relay component in remote config 
  Enable port forwarding for relay node
  Using requested port 7546
  ✔ Enable port forwarding for relay node [0.1s]
  Stopping port-forward for port [30212]
  

Cleanup

When you are done, destroy components in the reverse order of deployment.

Important: Always destroy components before destroying the network. Skipping this order can leave orphaned Helm releases and PVCs in your cluster.

1. Destroy JSON-RPC Relay

solo relay node destroy \
  -i node1 \
  --deployment "${SOLO_DEPLOYMENT}" \
  --cluster-ref kind-${SOLO_CLUSTER_NAME}

2. Destroy Mirror Node

solo mirror node destroy \
  --deployment "${SOLO_DEPLOYMENT}" \
  --force

3. Destroy Explorer

solo explorer node destroy \
  --deployment "${SOLO_DEPLOYMENT}" \
  --force

4. Destroy the Network

solo consensus network destroy \
  --deployment "${SOLO_DEPLOYMENT}" \
  --force

2.2.4 - Dynamically add, update, and remove Consensus Nodes

Overview

This guide covers how to dynamically manage consensus nodes in a running Solo network - adding new nodes, updating existing ones, and removing nodes that are no longer needed. All three operations can be performed without taking the network offline.

Prerequisites

Before proceeding, ensure you have:

• A running Solo network. If you don’t have one, deploy using one of the following methods:

  1. Quickstart - single command deployment using solo one-shot single deploy.
  2. Manual Deployment - step-by-step deployment with full control over each component.

• Set the required environment variables as described below:

    export SOLO_CLUSTER_NAME=solo
    export SOLO_NAMESPACE=solo
    export SOLO_CLUSTER_SETUP_NAMESPACE=solo-cluster
    export SOLO_DEPLOYMENT=solo-deployment
  

Key and Storage Concepts

Before running any node operation, it helps to understand two concepts that appear in the prepare step.

1. Cryptographic Keys

   Solo generates two types of keys for each consensus node:

   • Gossip keys — used for encrypted node-to-node communication within the network. Stored as s-private-node*.pem and s-public-node*.pem under ~/.solo/cache/keys/.
   • TLS keys — used to secure gRPC connections to the node. Stored as hedera-node*.crt and hedera-node*.key under ~/.solo/cache/keys/.

   When adding a new node, Solo generates a fresh key pair and stores it alongside the keys for existing nodes in the same directory. For more detail, see Where are my keys stored?.

2. Persistent Volume Claims (PVCs)

   By default, consensus node storage is ephemeral - data stored by a node is lost if its pod crashes or is restarted. This is intentional for lightweight local testing where persistence is not required.

   The --pvcs true flag creates Persistent Volume Claims (PVCs) for the node, ensuring its state survives pod restarts. Enable this flag for any node that needs to persist across restarts or that will participate in longer-running test scenarios.

   Note: PVCs are not enabled by default. Enable them only if your node needs to persist state across pod restarts.

3. Staging Directory

   The --output-dir context flag specifies a local staging directory where Solo writes all artifacts produced during prepare. Solo’s working files are stored under ~/.solo/ — if you use a relative path like context, the directory is created in your current working directory. Do not delete it until execute has completed successfully.

Adding a Node to an Existing Network

You can dynamically add a new consensus node to a running network without taking the network offline. This process involves three stages: preparing the node’s keys and configuration, submitting the on-chain transaction, and executing the addition.

Step 1: Prepare the new node

Generate the new node’s gossip and TLS keys, create its persistent volumes, and stage its configuration into an output directory:

    solo consensus dev-node-add prepare \
    --gossip-keys true \
    --tls-keys true \
    --deployment "${SOLO_DEPLOYMENT}" \
    --pvcs true \
    --admin-key <admin-key> \
    --node-alias node2 \
    --output-dir context

Step 2: Submit the transaction to add the node

Submit the on-chain transaction to register the new node with the network:

  solo consensus dev-node-add submit-transaction \
  --deployment "${SOLO_DEPLOYMENT}" \
  --input-dir context

Step 3: Execute the node addition

Apply the node addition and bring the new node online:

  solo consensus dev-node-add execute \
  --deployment "${SOLO_DEPLOYMENT}" \
  --input-dir context

Note: For a complete walkthrough with expected outputs, see the Node Create Transaction example.

Updating a Node

You can update an existing consensus node - for example, to upgrade its software version or modify its configuration - without removing it from the network.

Step 1: Prepare the update

Stage the updated configuration and any new software version for the target node:

  solo consensus dev-node-update prepare \
  --deployment "${SOLO_DEPLOYMENT}" \
  --node-alias node1 \
  --release-tag v0.61.0 \
  --output-dir context

Step 2: Submit the update transaction

Submit the on-chain transaction to register the node update with the network:

  solo consensus dev-node-update submit-transaction \
  --deployment "${SOLO_DEPLOYMENT}" \
  --input-dir context

Step 3: Execute the update

Apply the update and restart the node with the new configuration:

  solo consensus dev-node-update execute \
  --deployment "${SOLO_DEPLOYMENT}" \
  --input-dir context

Note: For a complete walkthrough with expected outputs, see the Node Update Transaction example.

Removing a Node from a Network

You can dynamically remove a consensus node from a running network without taking the remaining nodes offline.

Note: Removing a node permanently reduces the number of consensus nodes in the network. Ensure the remaining nodes meet the minimum threshold required for consensus before proceeding.

Step 1: Prepare the Node for Deletion

Stage the deletion context for the target node:

  solo consensus dev-node-delete prepare \
  --deployment "${SOLO_DEPLOYMENT}" \
  --node-alias node2 \
  --output-dir context

Step 2: Submit the delete transaction

Submit the on-chain transaction to deregister the node from the network:

  solo consensus dev-node-delete submit-transaction \
  --deployment "${SOLO_DEPLOYMENT}" \
  --input-dir context

Step 3: Execute the deletion

Remove the node and clean up its associated resources:

  solo consensus dev-node-delete execute \
  --deployment "${SOLO_DEPLOYMENT}" \
  --input-dir context

Note: For a complete walkthrough with expected outputs, see the Node Delete Transaction example.

2.3 - Attach JVM Debugger and Retrieve Logs

Overview

This guide covers three debugging workflows:

• Retrieve logs from a running consensus node using k9s or the Solo CLI
• Attach a JVM debugger in IntelliJ IDEA to a running or restarting node
• Save and restore network state files to replay scenarios across sessions

Prerequisites

Before proceeding, ensure you have completed the following:

• System Readiness — your local environment meets all hardware and software requirements.
• Quickstart — you have a running Solo cluster and are familiar with the basic Solo workflow.

You will also need:

• k9s installed (brew install k9s)
• IntelliJ IDEA with a Remote JVM Debug run configuration (for JVM debugging only)
• A local checkout of hiero-consensus-node that has been built with assemble or build (for JVM debugging only)

1. Retrieve Consensus Node Logs

Using k9s

Run k9s -A in your terminal to open the cluster dashboard, then select one of the network node pods.

Select the root-container and press s to open a shell inside the container.

Navigate to the Hedera application directory to browse logs and configuration:

cd /opt/hgcapp/services-hedera/HapiApp2.0/

From there you can inspect logs and configuration files:

[root@network-node1-0 HapiApp2.0]# ls -ltr data/config/
total 0
lrwxrwxrwx 1 root root 27 Dec  4 02:05 bootstrap.properties -> ..data/bootstrap.properties
lrwxrwxrwx 1 root root 29 Dec  4 02:05 application.properties -> ..data/application.properties
lrwxrwxrwx 1 root root 32 Dec  4 02:05 api-permission.properties -> ..data/api-permission.properties

[root@network-node1-0 HapiApp2.0]# ls -ltr output/
total 1148
-rw-r--r-- 1 hedera hedera       0 Dec  4 02:06 hgcaa.log
-rw-r--r-- 1 hedera hedera       0 Dec  4 02:06 queries.log
drwxr-xr-x 2 hedera hedera    4096 Dec  4 02:06 transaction-state
drwxr-xr-x 2 hedera hedera    4096 Dec  4 02:06 state
-rw-r--r-- 1 hedera hedera     190 Dec  4 02:06 swirlds-vmap.log
drwxr-xr-x 2 hedera hedera    4096 Dec  4 16:01 swirlds-hashstream
-rw-r--r-- 1 hedera hedera 1151446 Dec  4 16:07 swirlds.log

Using the Solo CLI (Alternative option)

To download hgcaa.log and swirlds.log as a zip archive without entering the container shell, run:

# Downloads logs to ~/.solo/logs/<namespace>/<timestamp>/
solo consensus diagnostics all --deployment solo-deployment

2. Attach a JVM Debugger in IntelliJ IDEA

Solo supports pausing node startup at a JDWP debug port so you can attach IntelliJ IDEA before the node begins processing transactions.

Configure IntelliJ IDEA

Create a Remote JVM Debug run configuration in IntelliJ IDEA.

For the Hedera Node application:

If you are working on the Platform test application instead:

Set any breakpoints you need before launching the Solo command in the next step.

Note: The local-build-path in the commands below references ../hiero-consensus-node/hedera-node/data. Adjust this path to match your local checkout location. Ensure the directory is up to date by running ./gradlew assemble in the hiero-consensus-node repo before proceeding.

Example 1 — Debug a node during initial network deployment

This example deploys a three-node network and pauses node2 for debugger attachment.

SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-e2e
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment

# Remove any previous state to avoid name collision issues
rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"

solo init
solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}

solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3

solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --debug-node-alias node2
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --debug-node-alias node2

When Solo reaches the active-check phase for node2, it pauses and displays:

❯ Check all nodes are ACTIVE
  Check node: node1,
  Check node: node2,  Please attach JVM debugger now.
  Check node: node3,
? JVM debugger setup for node2. Continue when debugging is complete? (y/N)

At this point, launch the remote debug configuration in IntelliJ IDEA. The node will stop at your breakpoint:

When you are done debugging, resume execution in IntelliJ, then type y in the terminal to allow Solo to continue.

Example 2 — Debug a node during a node add operation

This example starts a three-node network and then attaches a debugger while adding node4.

SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-e2e
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment

rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"

solo init
solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}

solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3

solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --pvcs true
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3

solo consensus node add --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys \
  --debug-node-alias node4 \
  --local-build-path ../hiero-consensus-node/hedera-node/data \
  --pvcs true

Example 3 — Debug a node during a node update operation

This example attaches a debugger to node2 while it restarts as part of an update operation.

SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-e2e
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment

rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"

solo init
solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}

solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3

solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3

solo consensus node update --deployment "${SOLO_DEPLOYMENT}" \
  --node-alias node2 \
  --debug-node-alias node2 \
  --local-build-path ../hiero-consensus-node/hedera-node/data \
  --new-account-number 0.0.7 \
  --gossip-public-key ./s-public-node2.pem \
  --gossip-private-key ./s-private-node2.pem \
  --release-tag v0.59.5

Example 4 — Debug a node during a node delete operation

This example attaches a debugger to node3 while node2 is being removed from the network.

SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-e2e
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment

rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"

solo init
solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}

solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3

solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3

solo consensus node destroy --deployment "${SOLO_DEPLOYMENT}" \
  --node-alias node2 \
  --debug-node-alias node3 \
  --local-build-path ../hiero-consensus-node/hedera-node/data

3. Save and Restore Network State

You can snapshot the state of a running network and restore it later. This is useful for replaying specific scenarios or sharing reproducible test cases with the team.

Save state

Stop the nodes first, then download the state archives:

# Stop all nodes before downloading state
solo consensus node stop --deployment "${SOLO_DEPLOYMENT}"

# Download state files to ~/.solo/logs/<namespace>/
solo consensus state download -i node1,node2,node3 --deployment "${SOLO_DEPLOYMENT}"

The state files are saved under ~/.solo/logs/:

└── logs
    ├── solo-e2e
    │   ├── network-node1-0-state.zip
    │   └── network-node2-0-state.zip
    └── solo.log

Restore state

Create a fresh cluster, deploy the network, then upload the saved state before starting the nodes:

SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-e2e
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment

rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"

solo init
solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}

solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3

solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node stop --deployment "${SOLO_DEPLOYMENT}"

# Upload previously saved state files
solo consensus node states -i node1,node2,node3 --deployment "${SOLO_DEPLOYMENT}"

# Restart the network using the uploaded state
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" --state-file network-node1-0-state.zip

2.4 - Customizing Solo with Tasks

Overview

The Task tool (task) is a task runner that enables you to deploy and customize Solo networks using infrastructure-as-code patterns. Rather than running individual Solo CLI commands, you can use predefined Taskfile targets to orchestrate complex deployment workflows with a single command.

This guide covers installing the Task tool, understanding available Taskfile targets, and using them to deploy networks with various configurations. It also points to maintained example projects that demonstrate common Solo workflows.

Note: This guide assumes you have cloned the Solo repository and have basic familiarity with command-line interfaces and Docker.

Prerequisites

Before you begin, ensure you have completed the following:

• System Readiness: Prepare your local environment (Docker, Kind, Kubernetes, and related tooling).
• Quickstart: You are familiar with the basic Solo workflow and the solo one-shot single deploy command.

Tip: Task-based workflows are ideal for developers who want to:

• Run the same deployment multiple times reliably.
• Customize network components (add mirror nodes, relays, block nodes, etc.).
• Use version control to track deployment configurations.
• Integrate Solo deployments into CI/CD pipelines.

Install the Task Tool

The Task tool is a dependency for using Taskfile targets in the Solo repository. Install it using one of the following methods:

Using Homebrew (macOS/Linux) (recommended)

brew install go-task/tap/go-task

Using npm

npm install -g @go-task/cli

Verify the installation:

task --version

Expected output:

Task version: v3.X.X

Using package managers

Visit the Task installation guide for additional installation methods for your operating system.

Understanding the Task Structure

The Solo repository uses a modular Task architecture located in the scripts/ directory:

scripts/
├── Taskfile.yml                    # Main entry point (includes other Taskfiles)
├── Taskfile.scripts.yml            # Core deployment and management tasks
├── Taskfile.examples.yml           # Example project tasks
├── Taskfile.release.yml            # Package publishing tasks
└── [other helper scripts]

How to Run Tasks

From the root directory or any example directory, run:

# Run the default task
task

# Run a specific task
task <task-name>

# Run tasks with variables
task <task-name> -- VAR_NAME=value

Deploy Network Configurations

Basic Network Deployment

Deploy a standalone Hiero Consensus Node network with a single command:

# From the repository root, navigate to scripts directory
cd scripts

# Deploy default network (2 consensus nodes)
task default

This command performs the following actions:

• Initializes Solo and downloads required dependencies.
• Creates a local Kubernetes cluster using Kind.
• Deploys 2 consensus nodes.
• Sets up gRPC and JSON-RPC endpoints for client access.

Deploy Network with Mirror Node

Deploy a network with a consensus node, mirror node, and Hiero Explorer:

cd scripts

task default-with-mirror

This configuration includes:

Access the Explorer at: http://localhost:8080

Deploy Network with Relay and Explorer

Deploy a network with consensus nodes, mirror node, explorer, and JSON-RPC relay for Ethereum-compatible access:

cd scripts

task default-with-relay

This configuration includes:

Access the services at:

• Explorer: http://localhost:8080
• JSON-RPC Relay: http://localhost:7546

Available Taskfile Targets

The Taskfile includes a comprehensive set of targets for deploying and managing Solo networks. Below are the most commonly used targets, organized by category.

Core Deployment Targets

These targets handle the primary deployment lifecycle:

Example: Deploy, then clean up

cd scripts

# Deploy the network
task default

# ... (use the network)

# Stop the network
task stop

# Remove all traces of the deployment
task clean

Cache and Log Cleanup

When cleaning up, you can selectively remove specific components:

Mirror Node Management

Add, configure, or remove mirror nodes from an existing deployment:

Example: Add mirror node to running network

cd scripts

# Start with a basic network
task default

# Add mirror node later
task solo:mirror-node

# Remove mirror node
task solo:destroyer-mirror-node

Explorer UI Management

Deploy or remove the Hiero Explorer for transaction/account viewing:

Example: Deploy network with explorer

cd scripts

task default
task solo:explorer

# Access at http://localhost:8080

JSON-RPC Relay Management

Deploy or remove the Relay for Ethereum-compatible access:

Example: Add relay to running network

cd scripts

task default-with-mirror
task solo:relay

# Access JSON-RPC at http://localhost:7546

Block Node Management

Deploy or remove block nodes for streaming block data:

Example: Deploy network with block node

cd scripts

task default
task solo:block:add

# Block node will stream block data

Infrastructure Tasks

Low-level tasks for managing clusters and network infrastructure:

| Task | Description |\n| ————————— | ———————————————————- | | cluster:create | Create a Kind (Kubernetes in Docker) cluster | | cluster:destroy | Delete the Kind cluster | | solo:cluster:setup | Setup cluster infrastructure and prerequisites | | solo:init | Initialize Solo (download tools and templates) | | solo:deployment:create | Create a new deployment configuration | | solo:deployment:attach | Attach an existing cluster to a deployment | | solo:network:deploy | Deploy the consensus network to the cluster | | solo:network:destroy | Destroy the consensus network |

Tip: Unless you need custom cluster management, use the higher-level tasks like default, install, or destroy which orchestrate these infrastructure tasks automatically.

Utility Tasks

Helpful tasks for inspecting and managing running networks:

Example: View network IPs and logs

cd scripts

# See which nodes are running and their IPs
task show:ips

# Retrieve node logs for debugging
task solo:node:logs

Database Tasks

Deploy external databases for specialized configurations:

Advanced Configuration with Environment Variables

You can customize Task behavior by setting environment variables before running tasks. Common variables include:

For a comprehensive reference of all available environment variables, see Using Environment Variables.

Example: Deploy with custom versions

cd scripts

# Deploy with specific component versions
CONSENSUS_NODE_VERSION=v0.66.0 \
MIRROR_NODE_VERSION=v0.139.0 \
task default-with-mirror

Example Projects

The Solo repository includes 14+ maintained example projects that demonstrate common Solo workflows. These examples serve as templates and starting points for custom implementations.

Getting Started with Examples

Each example is located in the examples/ directory and includes:

• Pre-configured Taskfile.yml with deployment settings.
• init-containers-values.yaml for customization.
• Example-specific README with detailed instructions.

To run an example:

cd examples/<example-name>

# Deploy the example
task

# Clean up when done
task clean

Available Examples

Network Setup Examples

• Address Book: Use Yahcli to pull ledger and mirror node address books for querying network state
• Network with Domain Names: Setup a network with custom domain names for nodes instead of IP addresses
• Network with Block Node: Deploy a network with block node for streaming block data

Configuration Examples

• Custom Network Config: Customize consensus network configuration for your specific needs
• Local Build with Custom Config: Deploy using a locally-built consensus node with custom configuration
• Consensus Node JVM Parameters: Customize JVM parameters (memory, GC settings, etc.) for consensus nodes

Database Examples

• External Database Test: Deploy Solo with an external PostgreSQL database instead of embedded storage
• Multi-Cluster Backup and Restore: Backup state from one cluster and restore to another using external database

State Management Examples

• State Save and Restore: Save the network state with mirror node, then restore to a new deployment
• Version Upgrade Test: Upgrade all network components to the current version to test compatibility

Node Transaction Examples

These examples demonstrate manual operations for adding, modifying, and removing nodes:

• Node Create Transaction: Create a new node manually using the NodeCreate transaction
• Node Update Transaction: Update an existing node configuration with NodeUpdate transaction
• Node Delete Transaction: Remove a node from the network with NodeDelete transaction

Integration Examples

• Hardhat with Solo: Test smart contracts locally with Hardhat using Solo as the test network
• One-Shot Falcon Deployment: One-shot deployment using Falcon (consensus node implementation)
• One-Shot Local Build: One-shot deployment using a locally-built consensus node

Testing Examples

• Rapid-Fire: Rapid-fire deployment and teardown commands for stress testing the deployment workflow
• Running Solo Inside Cluster: Deploy Solo within an existing Kubernetes cluster instead of creating a new one

Practical Workflows

Workflow 1: Quick Development Network with Logging

Deploy a network for development and debugging:

cd scripts

# Set logging level
export SOLO_LOG_LEVEL=debug

# Deploy with mirror and relay
task default-with-relay

# Retrieve logs if needed
task solo:node:logs

# View network endpoints
task show:ips

# Clean up
task clean

Workflow 2: Test Configuration Changes

Iterate on network configuration:

cd examples/custom-network-config

# Edit the Taskfile or init-containers-values.yaml

# Deploy with your changes
task

# Test your configuration

# Clean up and try again
task clean

Workflow 3: Upgrade Network Components

Test upgrading Solo components:

cd examples/version-upgrade-test

# Deploy with current versions
task

# The example automatically tests the upgrade path

# Clean up
task clean

Workflow 4: Backup and Restore Network State

Test disaster recovery and state migration:

cd examples/state-save-and-restore

# Deploy initial network with state
task

# The example includes backup/restore operations

# Clean up
task clean

Troubleshooting

Common Issues

Task command not found

Ensure Task is installed and on your PATH:

which task
task --version

Taskfile not found

Run Task commands from the scripts/ directory or an examples/ subdirectory where a Taskfile.yml exists:

cd scripts
task default

Insufficient resources

Some deployments require significant resources. Verify your Docker has at least 12 GB of memory and 6 CPU cores allocated:

docker info --format 'CPU: {{.NCPU}}, Memory: {{.MemTotal | div 1000000000}}GB'

Cluster cleanup issues

If the cluster becomes unstable, perform a full cleanup:

cd scripts

# Remove all traces
task clean

# As a last resort, manually delete the Kind cluster
kind delete cluster --name solo-e2e

Next Steps

After deploying a network with Task, explore:

• Using the JavaScript SDK: Interact with your network programmatically
• Using Network Load Generator: Stress test your network
• Environment Variables Reference: Fine-tune deployment behavior
• Solo CI Workflow: Integrate Solo deployments into CI/CD pipelines

Additional Resources

• Task Official Documentation
• Solo Repository
• Hiero Consensus Node
• Hiero Mirror Node
• JSON-RPC Relay

2.5 - Solo CI Workflow

Overview

This guide walks you through integrating Solo into a GitHub Actions CI pipeline - covering runner requirements, tool installation, and automated network deployment. Each step installs dependencies directly in the workflow, since CI runners are fresh environments with no pre-installed tools.

Prerequisites

Before proceeding, ensure you have completed the following:

• System Readiness — your local environment meets all hardware and software requirements.
• Quickstart — you are familiar with the basic Solo workflow and the solo one-shot single deploy command.

This guide assumes you are integrating Solo into a GitHub Actions workflow where each runner is a fresh environment. The steps below install all required tools directly inside the workflow rather than relying on pre-installed dependencies.

Runner Requirements

Solo requires a minimum of 6 CPU cores and 12 GB of memory on the runner. If these requirements are not met, Solo components may hang or fail to install during deployment.

Note: The Kubernetes cluster does not have full access to all memory available on the host. Setting Docker to 12 GB of memory means the Kind cluster running inside Docker will have access to less than 12 GB. Memory and CPU utilisation also increase over time as transaction load grows. The requirements above are validated for solo one-shot single deploy as documented in this guide.

To verify that your runner meets these requirements, add the following step to your workflow:

  - name: Check Docker Resources
    run: |
      read cpus mem <<<"$(docker info --format '{{.NCPU}} {{.MemTotal}}')"
      mem_gb=$(awk -v m="$mem" 'BEGIN{printf "%.1f", m/1000000000}')
      echo "CPU cores: $cpus"
      echo "Memory: ${mem_gb} GB"

Expected Output:

  CPU cores: 6
  Memory: 12 GB

Step 1: Set Up Kind

Install Kind to create and manage a local Kubernetes cluster in your workflow.

  - name: Setup Kind
    uses: helm/kind-action@a1b0e391336a6ee6713a0583f8c6240d70863de3
    with:
      install_only: true
      node_image: kindest/node:v1.31.4@sha256:2cb39f7295fe7eafee0842b1052a599a4fb0f8bcf3f83d96c7f4864c357c6c30
      version: v0.26.0
      kubectl_version: v1.31.4
      verbosity: 3
      wait: 120s

Step 2: Install Node.js

  - name: Set up Node.js
    uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
    with:
      node-version: 22.12.0

Step 3: Install Solo CLI

Install the Solo CLI globally using npm.

Important: Always pin the CLI version. Unpinned installs may pick up breaking changes from newer releases and cause unexpected workflow failures.

  - name: Install Solo CLI
    run: |
      set -euo pipefail
      npm install -g @hashgraph/solo@0.48.0
      solo --version
      kind --version

Step 4: Deploy Solo

Deploy a Solo network to your Kind cluster. This command creates and configures a fully functional local Hiero network, including:

• Consensus Node

• Mirror Node

• Mirror Node Explorer

• JSON-RPC Relay

    - name: Deploy Solo
      env:
        SOLO_CLUSTER_NAME: solo
        SOLO_NAMESPACE: solo
        SOLO_CLUSTER_SETUP_NAMESPACE: solo-cluster
        SOLO_DEPLOYMENT: solo-deployment
      run: |
        set -euo pipefail
        kind create cluster -n "${SOLO_CLUSTER_NAME}"
        solo one-shot single deploy | tee solo-deploy.log
  

Complete Example Workflow

The following is the full workflow combining all steps above. Copy this into your .github/workflows/ directory as a starting point.

  - name: Check Docker Resources
    run: |
      read cpus mem <<<"$(docker info --format '{{.NCPU}} {{.MemTotal}}')"
      mem_gb=$(awk -v m="$mem" 'BEGIN{printf "%.1f", m/1000000000}')
      echo "CPU cores: $cpus"
      echo "Memory: ${mem_gb} GB"
      
  - name: Setup Kind
    uses: helm/kind-action@a1b0e391336a6ee6713a0583f8c6240d70863de3
    with:
      install_only: true
      node_image: kindest/node:v1.31.4@sha256:2cb39f7295fe7eafee0842b1052a599a4fb0f8bcf3f83d96c7f4864c357c6c30
      version: v0.26.0
      kubectl_version: v1.31.4
      verbosity: 3
      wait: 120s
         
  - name: Set up Node.js
    uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
    with:
      node-version: 22.12.0
      
  - name: Install Solo CLI
    run: |
      set -euo pipefail
      npm install -g @hashgraph/solo@0.48.0
      solo --version
      kind --version
      
  - name: Deploy Solo
    env:
      SOLO_CLUSTER_NAME: solo
      SOLO_NAMESPACE: solo
      SOLO_CLUSTER_SETUP_NAMESPACE: solo-cluster
      SOLO_DEPLOYMENT: solo-deployment
    run: |
      set -euo pipefail
      kind create cluster -n "${SOLO_CLUSTER_NAME}"
      solo one-shot single deploy | tee solo-deploy.log

2.6 - CLI Reference

2.6.1 - Solo CLI Reference

Overview

This page is the canonical command reference for the Solo CLI.

• Use it to look up command paths, subcommands, and flags.
• Use solo <command> --help and solo <command> <subcommand> --help for runtime help on your installed version.
• For legacy command mappings, see CLI Migration Reference.

Output Formats (--output, -o)

Solo supports machine-readable output for version output and for command execution flows that honor the output format flag.

solo --version -o json
solo --version -o yaml
solo --version -o wide

Expected formats:

• json: JSON object output.
• yaml: YAML output.
• wide: plain text value-oriented output.

Global Flags

Global flags shown in root help:

• --dev: enable developer mode.
• --force-port-forward: force port forwarding for network services.
• -v, --version: print Solo version.

Command and Flag Reference

The sections below are generated from Solo CLI help output using the implementation on hiero-ledger/solo (main), commit f800d3c.

Root Help Output

Usage:
  solo <command> [options]

Commands:
  init         Initialize local environment
  config       Backup and restore component configurations for Solo deployments. These commands display what would be backed up or restored without performing actual operations.
  block        Block Node operations for creating, modifying, and destroying resources. These commands require the presence of an existing deployment.
  cluster-ref  Manages the relationship between Kubernetes context names and Solo cluster references which are an alias for a kubernetes context.
  consensus    Consensus Node operations for creating, modifying, and destroying resources. These commands require the presence of an existing deployment.
  deployment   Create, modify, and delete deployment configurations. Deployments are required for most of the other commands.
  explorer     Explorer Node operations for creating, modifying, and destroying resources.These commands require the presence of an existing deployment.
  keys         Consensus key generation operations
  ledger       System, Account, and Crypto ledger-based management operations. These commands require an operational set of consensus nodes and may require an operational mirror node.
  mirror       Mirror Node operations for creating, modifying, and destroying resources. These commands require the presence of an existing deployment.
  relay        RPC Relay Node operations for creating, modifying, and destroying resources. These commands require the presence of an existing deployment.
  one-shot     One Shot commands for new and returning users who need a preset environment type. These commands use reasonable defaults to provide a single command out of box experience.
  rapid-fire   Commands for performing load tests a Solo deployment

Options:

                                                                                     
     --dev                 Enable developer mode           [boolean] [default: false]
     --force-port-forward  Force port forward to access    [boolean] [default: true] 
                           the network services                                      
-v,  --version             Show version number             [boolean]