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.
The variables on this page configure Solo itself. They are not the same as the
variables Solo passes on to the external tools it runs (helm, kubectl, kind).
Those are filtered by an allowlist — see
Subprocess Environment Filtering
if a variable you set is not reaching one of those tools.
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.
General
| Environment Variable | Description | Default Value |
|---|---|---|
SOLO_HOME | Path to the Solo cache and log files | ~/.solo |
SOLO_CACHE_DIR | Path to the Solo cache directory | ~/.solo/cache |
SOLO_LOG_LEVEL | Logging level for Solo operations. Accepted values: trace, debug, info, warn, error | info |
SOLO_DEV_OUTPUT | Treat all commands as if the --debug flag were specified (--debug was formerly --dev) | false |
SOLO_CHAIN_ID | Chain ID of the Solo network | 298 |
FORCE_PODMAN | Force the use of Podman as the container engine when creating a new local cluster. Accepted values: true, false | false |
KUBECONFIG | Kubeconfig file, or :-separated list of files, that Solo uses to reach your clusters. When Solo creates the local cluster with rootful Podman on Linux, kind writes the kind-kind cluster, context and user into the first listed file that exists, else into the last listed file | ~/.kube/config |
Network and Node Identity
| Environment Variable | Description | Default Value |
|---|---|---|
DEFAULT_START_ID_NUMBER | Raw node ID number for the first consensus node. The first node account ID is resolved as 0.0.<DEFAULT_START_ID_NUMBER> | 3 |
SOLO_NODE_INTERNAL_GOSSIP_PORT | Internal gossip port used by the Hiero network | 50111 |
SOLO_NODE_EXTERNAL_GOSSIP_PORT | External gossip port used by the Hiero network | 50111 |
SOLO_NODE_DEFAULT_STAKE_AMOUNT | Default stake amount for a node | 500 |
GRPC_PORT | Local port-forward for consensus node gRPC. Default is 35211 for Solo 0.63+ (changed from 50211 to avoid Windows ephemeral-port conflicts). See Port availability. | 35211 |
LOCAL_NODE_START_PORT | Local node start port for the Solo network | 30212 |
NETWORK_NODE_LIFECYCLE_MODE | Selects the root container image Solo uses to run each consensus node and how it starts and stops the node process. Accepted values: solo-container (the solo-containers image, controlled by its /command/network-node-lifecycle helper) and consensus-node-image (the hiero-consensus-node deterministic image gcr.io/hedera-registry/consensus-node:<version>, whose platform jars are baked in and which Solo controls with s6-svc). In consensus-node-image mode Solo sets AUTO_START_CONSENSUS_SERVICE=false, skips the Fetch platform software step, and installs zip, unzip and curl in the root container. Version upgrade (solo consensus network upgrade) is not supported in consensus-node-image mode yet | solo-container |
Operator and Key Configuration
| Environment Variable | Description | Default Value |
|---|---|---|
SOLO_OPERATOR_ID | Operator account ID for the Solo network | 0.0.2 |
SOLO_OPERATOR_KEY | Operator private key for the Solo network | 302e020100... |
SOLO_OPERATOR_PUBLIC_KEY | Operator public key for the Solo network | 302a300506... |
FREEZE_ADMIN_ACCOUNT | Freeze admin account ID for the Solo network | 0.0.58 |
GENESIS_KEY | ED25519 genesis private key for a new Solo network. At solo consensus network deploy Solo stores it in the genesis-key Kubernetes secret and sets the genesis public key of the consensus nodes to match. Later commands read the secret first, then this variable | 302e020100... |
Note: Full key values are omitted above for readability. Refer to the source defaults for complete key strings.
Node Client Behaviour
| Environment Variable | Description | Default Value |
|---|---|---|
NODE_CLIENT_MIN_BACKOFF | Minimum wait time between retries, in milliseconds | 1000 |
NODE_CLIENT_MAX_BACKOFF | Maximum wait time between retries, in milliseconds | 1000 |
NODE_CLIENT_REQUEST_TIMEOUT | Time a transaction or query retries on a “busy” network response, in milliseconds | 600000 |
NODE_CLIENT_MAX_ATTEMPTS | Maximum number of attempts for node client operations | 600 |
NODE_CLIENT_SDK_PING_MAX_RETRIES | Maximum number of retries for node health pings | 5 |
NODE_CLIENT_SDK_PING_RETRY_INTERVAL | Interval between node health ping retries, in milliseconds | 10000 |
NODE_COPY_CONCURRENT | Number of concurrent threads used when copying files to a node | 4 |
EXPERIMENTAL_COPY_WRAPS_LIB_IN_PARALLEL | Copy the WRAPS proving-key library to every consensus node concurrently during solo network deploy, instead of one node at a time. Concurrent copies finish faster on a network deploy with many nodes and ample bandwidth, but can saturate a constrained connection when several multi-hundred-megabyte copies run at once. Accepted values: true, false | false |
LOCAL_BUILD_COPY_RETRY | Number of retries for local build copy operations | 3 |
ACCOUNT_UPDATE_BATCH_SIZE | Number of accounts to update in a single batch operation | 10 |
Pod and Network Readiness
| Environment Variable | Description | Default Value |
|---|---|---|
PODS_RUNNING_MAX_ATTEMPTS | Maximum number of attempts to check if pods are running | 900 |
PODS_RUNNING_DELAY | Interval between pod running checks, in milliseconds | 1000 |
PODS_READY_MAX_ATTEMPTS | Maximum number of attempts to check if pods are ready | 300 |
PODS_READY_DELAY | Interval between pod ready checks, in milliseconds | 2000 |
NETWORK_NODE_ACTIVE_MAX_ATTEMPTS | Maximum number of attempts to check if network nodes are active | 300 |
NETWORK_NODE_ACTIVE_DELAY | Interval between network node active checks, in milliseconds | 1000 |
NETWORK_NODE_ACTIVE_TIMEOUT | Maximum wait time for network nodes to become active, in milliseconds | 1000 |
NETWORK_PROXY_MAX_ATTEMPTS | Maximum number of attempts to check if the network proxy is running | 300 |
NETWORK_PROXY_DELAY | Interval between network proxy checks, in milliseconds | 2000 |
NETWORK_DESTROY_WAIT_TIMEOUT | Maximum wait time for network teardown to complete, in milliseconds | 120 |
STATE_DOWNLOAD_STABLE_MAX_ATTEMPTS | Maximum number of attempts to check whether a consensus node’s saved state has stopped changing on disk, before solo consensus state download archives it and before solo consensus network freeze stops the nodes | 180 |
STATE_DOWNLOAD_STABLE_DELAY | Interval between saved state stability checks, in milliseconds | 2000 |
STATE_DOWNLOAD_STABLE_POLLS_REQUIRED | Number of consecutive checks that must report an unchanged saved state before it is treated as stable | 3 |
Block Node
| Environment Variable | Description | Default Value |
|---|---|---|
BLOCK_NODE_PODS_RUNNING_MAX_ATTEMPTS | Maximum number of attempts to check if block node pods are running | 900 |
BLOCK_NODE_PODS_RUNNING_DELAY | Interval between block node pod running checks, in milliseconds | 1000 |
BLOCK_NODE_ACTIVE_MAX_ATTEMPTS | Maximum number of attempts to check if block nodes are active | 100 |
BLOCK_NODE_ACTIVE_DELAY | Interval between block node active checks, in milliseconds | 60 |
BLOCK_NODE_ACTIVE_TIMEOUT | Maximum wait time for block nodes to become active, in milliseconds | 60 |
BLOCK_STREAM_STREAM_MODE | The blockStream.streamMode value in consensus node application properties. Only applies when a Block Node is deployed | BOTH |
BLOCK_STREAM_WRITER_MODE | The blockStream.writerMode value in consensus node application properties. Only applies when a Block Node is deployed | FILE_AND_GRPC |
Relay Node
| Environment Variable | Description | Default Value |
|---|---|---|
RELAY_PODS_RUNNING_MAX_ATTEMPTS | Maximum number of attempts to check if relay pods are running | 900 |
RELAY_PODS_RUNNING_DELAY | Interval between relay pod running checks, in milliseconds | 1000 |
RELAY_PODS_READY_MAX_ATTEMPTS | Maximum number of attempts to check if relay pods are ready | 100 |
RELAY_PODS_READY_DELAY | Interval between relay pod ready checks, in milliseconds | 1000 |
Mirror Node
| Environment Variable | Description | Default Value |
|---|---|---|
DISABLE_IMPORTER_SPRING_PROFILES | Disable automatic configuration of Mirror Node importer Spring profiles for block-node integration. | false |
SPRING_PROFILES_ACTIVE | Spring profiles to use for the Mirror Node importer when automatic importer profile configuration is enabled. | blocknode |
MIRROR_NODE_SCHEMA_READY_MAX_ATTEMPTS | Maximum number of attempts to check if the Mirror Node database schema has been built (signalled by importer pod readiness) | 900 |
MIRROR_NODE_SCHEMA_READY_DELAY | Interval between Mirror Node database schema checks, in milliseconds | 2000 |
MIRROR_NODE_IMPORTER_DETECT_MAX_ATTEMPTS | Maximum number of attempts to detect a running Mirror Node importer pod. If no importer pod is found, the database schema wait is skipped | 15 |
MIRROR_NODE_IMPORTER_DETECT_DELAY | Interval between Mirror Node importer pod detection attempts, in milliseconds | 2000 |
MIRROR_NODE_CHART_UPGRADE_MAX_ATTEMPTS | Maximum number of attempts to install or upgrade the Mirror Node Helm chart before failing. Retries ride out transient Kubernetes API server outages | 3 |
MIRROR_NODE_CHART_UPGRADE_RETRY_DELAY_SECS | Delay between Mirror Node Helm chart install/upgrade attempts, in seconds | 15 |
MIRROR_EXTERNAL_DATABASE_CLIENT_IMAGE | Image of the short-lived psql pod that mirror node add / mirror node upgrade with --use-external-database starts to grant the readonly role to mirror_rest on the external database. The image must provide psql and sleep. Override it for private or air-gapped registries | docker.io/bitnamilegacy/postgresql-repmgr:17.6.0-debian-12-r2 |
Load Balancer
| Environment Variable | Description | Default Value |
|---|---|---|
LOAD_BALANCER_CHECK_DELAY_SECS | Delay between load balancer status checks, in seconds | 5 |
LOAD_BALANCER_CHECK_MAX_ATTEMPTS | Maximum number of attempts to check load balancer status | 60 |
Lease Management
| Environment Variable | Description | Default Value |
|---|---|---|
SOLO_LEASE_ACQUIRE_ATTEMPTS | Number of attempts to acquire a lock before failing | 10 |
SOLO_LEASE_DURATION | Duration in seconds for which a lock is held before expiration | 20 |
Component Versions
| Environment Variable | Description |
|---|---|
CONSENSUS_NODE_VERSION | Release version of the Consensus Node to use |
BLOCK_NODE_VERSION | Release version of the Block Node to use |
MIRROR_NODE_VERSION | Release version of the Mirror Node to use |
EXPLORER_VERSION | Release version of the Explorer to use |
RELAY_VERSION | Release version of the JSON-RPC Relay to use |
INGRESS_CONTROLLER_VERSION | Release version of the HAProxy Ingress Controller to use |
SOLO_CHART_VERSION | Release version of the Solo Helm charts to use |
SOLO_CHEETAH_VERSION | Image version for the solo-deployment chart’s Cheetah component |
SOLO_CONTAINERS_VERSION | Image version for the solo-deployment chart’s Solo containers component |
MINIO_OPERATOR_VERSION | Release version of the MinIO Operator to use |
PROMETHEUS_STACK_VERSION | Release version of the Prometheus Stack to use |
GRAFANA_ALLOY_VERSION | Helm chart version of Grafana Alloy installed by solo cluster-ref config setup --grafana-alloy |
LOKI_VERSION | Helm chart version of the Loki log store installed by solo cluster-ref config setup --grafana-alloy |
GRAFANA_PODLOGS_CRD_VERSION | Grafana Alloy release tag the PodLogs custom resource definition is fetched from during solo network deploy --enable-monitoring-support |
Tip: To pin component versions for a
solo one-shot single deploy, prefix the command with these variables. See the One-Shot Deployment section below for an example.
Edge Component Versions
These variables only take effect when solo one-shot single deploy or
solo one-shot multi deploy is invoked with the --edge flag (solo one-shot falcon deploy does not accept --edge in v0.72.0). They let you point a
one-shot deploy at arbitrary component tags — release candidates,
pre-releases, or any other tag the component’s registry exposes — without
rebuilding Solo.
| Component | Environment Variable | Falls back to |
|---|---|---|
| Consensus Node | CONSENSUS_NODE_EDGE_VERSION | CONSENSUS_NODE_VERSION |
| Mirror Node | MIRROR_NODE_EDGE_VERSION | MIRROR_NODE_VERSION |
| JSON-RPC Relay | RELAY_EDGE_VERSION | RELAY_VERSION |
| Explorer | EXPLORER_EDGE_VERSION | EXPLORER_VERSION |
| Block Node | BLOCK_NODE_EDGE_VERSION | BLOCK_NODE_VERSION |
| Solo Chart | SOLO_CHART_EDGE_VERSION | SOLO_CHART_VERSION |
Set only the variables for components you want to override; the rest use their
compiled-in edge defaults. Without --edge, every *_EDGE_VERSION variable is
ignored.
For full usage, examples, version-format rules, and troubleshooting, see One-Shot Deploy with Custom Component Versions.
Helm Chart URLs
| Environment Variable | Description | Default Value |
|---|---|---|
JSON_RPC_RELAY_CHART_URL | Helm chart repository URL for the JSON-RPC Relay | https://hiero-ledger.github.io/hiero-json-rpc-relay/charts |
MIRROR_NODE_CHART_URL | Helm chart repository URL for the Mirror Node | https://hashgraph.github.io/hedera-mirror-node/charts |
EXPLORER_CHART_URL | Helm chart repository URL for the Explorer | oci://ghcr.io/hiero-ledger/hiero-mirror-node-explorer/hiero-explorer-chart |
INGRESS_CONTROLLER_CHART_URL | Helm chart repository URL for the ingress controller | https://haproxy-ingress.github.io/charts |
PROMETHEUS_OPERATOR_CRDS_CHART_URL | Helm chart repository URL for the Prometheus Operator CRDs | https://prometheus-community.github.io/helm-charts |
GRAFANA_ALLOY_CHART_URL | Helm chart repository URL for Grafana Alloy | https://grafana.github.io/helm-charts |
LOKI_CHART_URL | Helm chart repository URL for Loki | https://grafana.github.io/helm-charts |
NETWORK_LOAD_GENERATOR_CHART_URL | Helm chart repository URL for the Network Load Generator | oci://swirldslabs.jfrog.io/load-generator-helm-release-local |
Local Helm Chart Directories
Chart owners can test an unpublished chart by pointing Solo at a local chart
directory. Only the chart templates are local: every container image the chart
references must already be pullable by the cluster (published to a registry or
loaded with kind load docker-image). These variables are the equivalent of the
--block-node-chart-dir, --explorer-chart-dir, --mirror-node-chart-dir and
--relay-chart-dir flags, and the flag takes precedence when both are set.
| Environment Variable | Description | Default Value |
|---|---|---|
SOLO_BLOCK_NODE_CHART_DIR | Directory that contains the block node chart (block-node-server), e.g. /path/to/hiero-block-node/charts | unset (published chart) |
SOLO_EXPLORER_CHART_DIR | The explorer chart directory itself (the one holding Chart.yaml), e.g. /path/to/hiero-mirror-node-explorer/_frontend/chart | unset (published chart) |
SOLO_MIRROR_NODE_CHART_DIR | Directory that contains the mirror node chart (hedera-mirror), e.g. /path/to/hiero-mirror-node/charts | unset (published chart) |
SOLO_RELAY_CHART_DIR | Directory that contains the JSON-RPC relay chart (hedera-json-rpc), e.g. /path/to/hiero-json-rpc-relay/charts | unset (published chart) |
Note: The explorer variable takes the chart directory itself, while the other three take the directory that contains the chart. Use absolute paths: Solo does not expand
~inside the value.
For example, to deploy a network with a local mirror node chart:
SOLO_MIRROR_NODE_CHART_DIR=/path/to/hiero-mirror-node/charts solo one-shot single deploy
Network Load Generator
| Environment Variable | Description | Default Value |
|---|---|---|
NETWORK_LOAD_GENERATOR_CHART_VERSION | Release version of the Network Load Generator Helm chart to use | v0.7.0 |
NETWORK_LOAD_GENERATOR_PODS_RUNNING_MAX_ATTEMPTS | Maximum number of attempts to check if Network Load Generator pods are running | 900 |
NETWORK_LOAD_GENERATOR_POD_RUNNING_DELAY | Interval between Network Load Generator pod running checks, in milliseconds | 1000 |
One-Shot Deployment
| Environment Variable | Description | Default Value |
|---|---|---|
ONE_SHOT_WITH_BLOCK_NODE | Deploy Block Node as part of a one-shot deployment | false |
MIRROR_NODE_PINGER_TPS | Transactions per second for the Mirror Node monitor pinger. Set to 0 to disable | 5 |
CONSENSUS_NODE_EDGE_VERSION | Edge (newer-than-default) consensus node version used by --edge in one-shot deploys. Falls back to CONSENSUS_NODE_VERSION. | v0.74.0-rc.1 |
MIRROR_NODE_EDGE_VERSION | Edge mirror node version used by --edge in one-shot deploys. Falls back to MIRROR_NODE_VERSION. | v0.153.1 |
EXPLORER_EDGE_VERSION | Edge explorer version used by --edge in one-shot deploys. Falls back to EXPLORER_VERSION. | 26.0.0 |
RELAY_EDGE_VERSION | Edge relay version used by --edge in one-shot deploys. Falls back to RELAY_VERSION. | 0.76.2 |
BLOCK_NODE_EDGE_VERSION | Edge block node version used by --edge in one-shot deploys. Falls back to BLOCK_NODE_VERSION. | 0.31.0 |
Pinning Component Versions
solo one-shot single deploy does not yet expose CLI flags for pinning
individual component versions. To run a one-shot deployment against specific
releases, prefix the command with the
Component Versions environment variables:
CONSENSUS_NODE_VERSION=v0.73.0 MIRROR_NODE_VERSION=v0.153.1 solo one-shot single deploy
Any of the *_VERSION variables listed in
Component Versions can be combined in the same command
to pin multiple components at once.
Note:
- This is the current recommended approach for version pinning in one-shot deployments.
- CLI flags for version overrides on
one-shotare planned for Q2 — tracked in hiero-ledger/solo#4242.- Environment variables will remain valid for one-off overrides after the CLI flags land, so the form above will continue to work.
Image Cache
Solo caches the container images it deploys as local archives to speed up
repeat deployments. The cache is enabled by default; these variables disable it
per context. See Solo Image Cache for
the full feature and the solo cache image commands.
| Environment Variable | Description | Default |
|---|---|---|
ENABLE_IMAGE_CACHE | Set to false to disable the image cache during solo one-shot deploys. Requires Solo v0.78.0 or later (earlier releases have an inverted-logic bug in this flag). | enabled |
SOLO_NO_CACHE | Set to true to skip the image pull during an npm global install. | enabled |
HOMEBREW_NO_SOLO_CACHE | Set to any value to skip the image pull during a Homebrew install. | enabled |
CACHE_IMAGE_MAX_CONCURRENCY | Max concurrent image cache pull/load operations | 12 |
Note: The cached component versions follow the same environment-variable mechanism as Pinning Component Versions above - the
*_VERSIONenvironment variables affect the images the cache pulls, but the--*-versionCLI flags do not.