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 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

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:

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.

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.