Simple Solo Setup

• 1: System Readiness
• 2: Quickstart
• 3: Managing Your Network
• 4: Cleanup

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 and Solo, plus kubectl and Helm as dependencies.
• one-shot commands — automatically install Kind and Podman (if Docker is not found). kubectl and Helm are not auto-installed and must be pre-installed.

Pre-installation Requirements

Before running solo one-shot single deploy, you must have:

• A container runtime: either Docker Desktop (macOS/Windows) or Docker Engine/Podman (Linux). Solo cannot install a container runtime.
• kubectl and Helm: Solo requires these pre-installed. The one-shot command checks for their presence but does not install them.
  • Homebrew users: These are installed automatically as dependencies of the solo formula.
  • npm install users (Linux/WSL2): Install kubectl and Helm manually before running Solo.

Important: The one-shot deployment will fail immediately if kubectl or Helm are missing, even on macOS/Windows where Homebrew typically installs them as dependencies.

Docker

Solo requires Docker Desktop (macOS, Windows) or Docker Engine / Podman (Linux) with sufficient resources:

• Memory: at least 12 GB available for containers.
• CPU: at least 6 cores available for containers.

Configure Resources by Platform

macOS and Windows (Docker Desktop)

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.

Linux

Docker Engine on Linux uses system memory directly and does not have a resource allocation interface like Docker Desktop.

Resource Check:

• Ensure your machine has at least 12 GB of free RAM available before running solo one-shot single deploy.
• Check available memory with: free -h
• If you have insufficient RAM, the deployment may fail or pods may become unhealthy.

Podman on Linux: If using Podman instead of Docker Engine, ensure your system has at least 12 GB of free RAM available.

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 @hiero-ledger/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.

Clean up legacy npm installations

If you previously installed Solo via npm (for example, from older workshops or documentation), remove the legacy installation to avoid conflicts:

# Remove legacy npm-based Solo installation (if present)
[[ "$(command -v npm >/dev/null 2>&1 && echo 0 || echo 1)" -eq 0 ]] && { npm uninstall -g @hiero-ledger/solo >/dev/null 2>&1 || /bin/true }

Full environment reset

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

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 (alternative installation method):

  npm install -g @hiero-ledger/solo@latest
  

  Note: npm installation is an alternative to Homebrew. The Homebrew tap is the recommended installation method as it includes kubectl and Helm as dependencies and may have more up-to-date releases.

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 multi deploy --num-consensus-nodes 3

solo one-shot multi 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, Solo sets up port-forwards so you can reach your local services. The endpoints below are the default ports for Solo 0.63 and later:

Open http://localhost:38080 in your browser to explore your network.

Port availability

The ports above are Solo’s defaults. Solo uses kubectl port-forward to tunnel traffic from your machine to services running inside Kubernetes. Before opening each tunnel, Solo tries the configured port:

• If the port is free, Solo logs: Using requested port <port>.
• If the port is already occupied (by another process, or by a previous Solo session that did not clean up its port-forwards), Solo finds the next available port and logs: Using available port <port>.

The actual ports used are printed at the end of solo one-shot single deploy and saved to a file.

Note: The commands below use $(cat ~/.solo/cache/last-one-shot-deployment.txt) to look up the deployment name automatically. This cache file is only created by solo one-shot commands. If you deployed using individual CLI commands, this file does not exist - find your deployment name with solo deployment config list instead, then substitute it in place of the $(cat ...) subshell.

To see the active port assignments:

cat ~/.solo/one-shot-$(cat ~/.solo/cache/last-one-shot-deployment.txt)/forwards

To check deployment info including port assignments:

solo deployment config info --deployment $(cat ~/.solo/cache/last-one-shot-deployment.txt)

To restore port-forwards after a system restart without redeploying:

solo deployment refresh port-forwards --deployment $(cat ~/.solo/cache/last-one-shot-deployment.txt)

Endpoints for Solo 0.62 and earlier

If you are using Solo 0.62 or earlier, the default port-forward targets differ:

Open http://localhost:8080 in your browser to explore your network.

Note: localhost:5551 is the direct Mirror Node REST service, accessible only via manual kubectl port-forward, and is being phased out. Always use the ingress-based port (8081 for Solo 0.62 and earlier, 38081 for Solo 0.63+).

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 — the deployment name you passed to solo one-shot single deploy, or the default one-shot if you did not specify --deployment:

one-shot% 

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.

Verify Network is Working

To confirm your Hedera network is fully operational, create a test account using the Ledger account creation command:

solo ledger account create --deployment <deployment-name>

Example output:

 *** new account created ***
-------------------------------------------------------------------------------
{
  "accountId": "0.0.1001",
  "publicKey": "302a300506032b6570032100439379b330f3b57b5deffda196c7c0c3387f3330a838c021954303e260606f24",
  "balance": 100
}

Once the account is created, verify it in the web-based Explorer UI:

1. Open your browser to http://localhost:38080
2. In the search bar, enter the account ID (e.g., 0.0.1001)
3. View the account details, balance, and transaction history

This confirms that:

• The network is processing transactions
• The consensus node is responding correctly
• The mirror node is indexing transactions
• The explorer is displaying data properly

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>

Important: Solo deploys each network into a Kubernetes namespace. For one-shot deployments, the namespace defaults to one-shot (matching the default deployment name). You can override it by passing --namespace to solo one-shot single deploy.

To find your deployment namespace, use any of:

# Look up the namespace Solo recorded for this deployment
solo deployment config info --deployment <deployment-name>

# Or list all namespaces and pick the one matching your deployment
kubectl get ns

# Or inspect pods and use the NAMESPACE column
kubectl get pods -A | grep -v kube-system

For one-shot deployments the namespace matches the deployment name in ~/.solo/cache/last-one-shot-deployment.txt (default: one-shot).

Replace <namespace> and <pod-name> with the values from your deployment.

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.

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:

• Uninstalls all component Helm releases (consensus, mirror, relay, explorer).
• Removes the Solo cluster chart and disconnects the cluster reference.
• Deletes the deployment from Solo’s local configuration and clears the cache.
• Does NOT delete the Kind cluster - the cluster persists after destroy.

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.