Advanced on Solo

One-shot Falcon Deployment

Mon, 01 Jan 0001 00:00:00 +0000

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.

Use One-shot 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:

Solo CLI Reference

Mon, 01 Jan 0001 00:00:00 +0000

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.

Using Environment Variables

Mon, 01 Jan 0001 00:00:00 +0000

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.

Setting environment variables

How you set a variable depends on your shell. Use the tab for your platform:

# For a single command only
CONSENSUS_NODE_VERSION=v0.73.0 solo one-shot single deploy

# For the current session
export CONSENSUS_NODE_VERSION=v0.73.0

# Persist across sessions (add to ~/.bashrc or ~/.zshrc)
echo 'export CONSENSUS_NODE_VERSION=v0.73.0' >> ~/.zshrc

# For the current session
$env:CONSENSUS_NODE_VERSION = 'v0.73.0'

# Persist for your user (all future sessions)
[System.Environment]::SetEnvironmentVariable('CONSENSUS_NODE_VERSION', 'v0.73.0', 'User')

# Or add it to your PowerShell profile
Add-Content $PROFILE '$env:CONSENSUS_NODE_VERSION = "v0.73.0"'

Tip: Variables set in your shell environment (or persisted as shown above) take effect automatically for all subsequent Solo commands.

Advanced Solo Setup

Mon, 01 Jan 0001 00:00:00 +0000

CLI Migration Reference

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Use this page when migrating scripts or runbooks from legacy Solo CLI command paths (< v0.44.0) to the current command structure.

For full current syntax and flags, see Solo CLI Reference.

Legacy to Current Mapping

Legacy command	Current command
`init`	`init`
`block node add`	`block node add`
`block node destroy`	`block node destroy`
`block node upgrade`	`block node upgrade`
`account init`	`ledger system init`
`account update`	`ledger account update`
`account create`	`ledger account create`
`account get`	`ledger account info`
`quick-start single deploy`	`one-shot single deploy`
`quick-start single destroy`	`one-shot single destroy`
`cluster-ref connect`	`cluster-ref config connect`
`cluster-ref disconnect`	`cluster-ref config disconnect`
`cluster-ref list`	`cluster-ref config list`
`cluster-ref info`	`cluster-ref config info`
`cluster-ref setup`	`cluster-ref config setup`
`cluster-ref reset`	`cluster-ref config reset`
`deployment add-cluster`	`deployment cluster attach`
`deployment list`	`deployment config list`
`deployment create`	`deployment config create`
`deployment delete`	`deployment config delete`
`explorer deploy`	`explorer node add`
`explorer destroy`	`explorer node destroy`
`mirror-node deploy`	`mirror node add`
`mirror-node destroy`	`mirror node destroy`
`relay deploy`	`relay node add`
`relay destroy`	`relay node destroy`
`network deploy`	`consensus network deploy`
`network destroy`	`consensus network destroy`
`node keys`	`keys consensus generate`
`node freeze`	`consensus network freeze`
`node upgrade`	`consensus network upgrade`
`node setup`	`consensus node setup`
`node start`	`consensus node start`
`node stop`	`consensus node stop`
`node restart`	`consensus node restart`
`node refresh`	`consensus node refresh`
`node add`	`consensus node add`
`node update`	`consensus node update`
`node delete`	`consensus node destroy`
`node add-prepare`	`consensus dev-node-add prepare`
`node add-submit-transaction`	`consensus dev-node-add submit-transactions`
`node add-execute`	`consensus dev-node-add execute`
`node update-prepare`	`consensus dev-node-update prepare`
`node update-submit-transaction`	`consensus dev-node-update submit-transactions`
`node update-execute`	`consensus dev-node-update execute`
`node upgrade-prepare`	`consensus dev-node-upgrade prepare`
`node upgrade-submit-transaction`	`consensus dev-node-upgrade submit-transactions`
`node upgrade-execute`	`consensus dev-node-upgrade execute`
`node delete-prepare`	`consensus dev-node-delete prepare`
`node delete-submit-transaction`	`consensus dev-node-delete submit-transactions`
`node delete-execute`	`consensus dev-node-delete execute`
`node prepare-upgrade`	`consensus dev-freeze prepare-upgrade`
`node freeze-upgrade`	`consensus dev-freeze freeze-upgrade`
`node logs`	`deployment diagnostics logs`
`node download-generated-files`	No direct equivalent. Use `deployment diagnostics all` or `deployment diagnostics debug` based on intent.
`node states`	`consensus state download`

Notes

Current command tree includes additional commands not present in legacy CLI (for example ledger account predefined, rapid-fire load start, and consensus node collect-jfr).

Falcon Values File Reference

Mon, 01 Jan 0001 00:00:00 +0000

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:

Section	Solo subcommand
`network`	`solo consensus network deploy`
`setup`	`solo consensus node setup`
`consensusNode`	`solo consensus node start`
`mirrorNode`	`solo mirror node add`
`explorerNode`	`solo explorer node add`
`relayNode`	`solo relay node add`
`blockNode`	`solo block node add`

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.

Network Deployments

Mon, 01 Jan 0001 00:00:00 +0000

Attach JVM Debugger and Retrieve Logs

Mon, 01 Jan 0001 00:00:00 +0000

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:

One-Shot Deploy with Custom Component Versions

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Solo’s one-shot single deploy and one-shot multi deploy commands accept an --edge flag that switches every component from its built-in stable default to a separate set of “edge” versions. Each edge version is read from an environment variable at startup, so you can pin any component to any tag the container registry exposes — including release candidates and unreleased builds — without editing Solo source or rebuilding the CLI.

Step-by-Step Manual Deployment

Mon, 01 Jan 0001 00:00:00 +0000

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.
Set your environment variables if you have not already done so:

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

$env:SOLO_CLUSTER_NAME = 'solo'
$env:SOLO_NAMESPACE = 'solo-deployment'
$env:SOLO_CLUSTER_SETUP_NAMESPACE = 'solo-cluster'
$env:SOLO_DEPLOYMENT = 'solo-deployment'

Deployment Steps

Note: The expected output blocks below are fetched from the latest published Solo release at build time and will always reflect the current version.

Using Network Load Generator with Solo

Mon, 01 Jan 0001 00:00:00 +0000

Using Network Load Generator with Solo

The Network Load Generator (NLG) is a benchmarking tool that stress tests Hiero networks by generating configurable transaction loads. Use it to validate the performance and stability of your Solo network before deploying to production or running integration tests.

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 and are familiar with the basic Solo workflow.

Step 1: Start a Load Test

Use the rapid-fire load start command to install the NLG Helm chart and begin a load test against your deployment.

Customizing Solo with Tasks

Mon, 01 Jan 0001 00:00:00 +0000

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.

Dynamically add, update, and remove Consensus Nodes

Mon, 01 Jan 0001 00:00:00 +0000

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:

Solo CI Workflow

Mon, 01 Jan 0001 00:00:00 +0000

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.

Run Performance Tests Locally

Mon, 01 Jan 0001 00:00:00 +0000

Overview

This guide shows how to run the Solo E2E performance test on a local machine.

Prerequisites

task, node, npm, kubectl, and kind installed
Docker running
Solo dependencies installed (npm ci)

Run the Performance Test

From the repository root:

task test-setup
task test-e2e-performance

The test uses one-shot single deploy/destroy flow and then runs rapid-fire load tests.

Optional: Use a Local Consensus Node Build

If you already have a local consensus node build, set SOLO_LOCAL_BUILD_PATH so commands that consume --local-build-path can use it by default:

CLI Reference

Mon, 01 Jan 0001 00:00:00 +0000

Solo Image Cache

Mon, 01 Jan 0001 00:00:00 +0000

Overview

A Solo network runs roughly 29 container images (consensus node, mirror node, JSON-RPC relay, Explorer, MinIO, and supporting services). The image cache pre-pulls those images and stores them as local .tar archives, so repeat deployments load them from disk instead of re-downloading them from their registries.

Solo populates and uses the cache automatically in two places:

At install time - Homebrew and npm installs pre-pull the default images.
During solo one-shot deploys - Solo pulls and loads the cached images as pipeline phases before the network is deployed.

You can also manage the cache directly with the solo cache image commands.

Advanced on Solo

One-shot Falcon Deployment

Overview

Solo CLI Reference

Overview

Output Formats (--output, -o)

Using Environment Variables

Overview

Setting environment variables

Advanced Solo Setup

CLI Migration Reference

Overview

Legacy to Current Mapping

Notes

Falcon Values File Reference

Overview

Network Deployments

Attach JVM Debugger and Retrieve Logs

Overview

Prerequisites

One-Shot Deploy with Custom Component Versions

Overview

Step-by-Step Manual Deployment

Overview

Prerequisites

Deployment Steps

Using Network Load Generator with Solo

Using Network Load Generator with Solo

Prerequisites

Step 1: Start a Load Test

Customizing Solo with Tasks

Overview

Dynamically add, update, and remove Consensus Nodes

Overview

Prerequisites

Solo CI Workflow

Overview

Prerequisites

Run Performance Tests Locally

Overview

Prerequisites

Run the Performance Test

Optional: Use a Local Consensus Node Build

CLI Reference

Solo Image Cache

Overview

Output Formats (`--output`, `-o`)