System Readiness

Verify hardware and software requirements before deploying a local Hiero test network with Solo. Check system prerequisites, install Docker/Podman, configure platform-specific settings, and ensure your machine is ready.
Categories:
Tags:

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 — natively with PowerShell, or 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:

ConfigurationMinimum RAMRecommended RAMMinimum CPUMinimum Storage
Single-node12 GB16 GB4 cores20 GB free
Multi-node (3+ nodes)16 GB24 GB8 cores20 GB free

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 sets up most of the tools it needs for you. The table below shows what each install method provides, what Solo provisions automatically, and what you must install yourself.

ToolRequired versionHow it is installed
Sololatestbrew install hiero-ledger/tools/solo, or npm install -g @hiero-ledger/solo
Node.js>= 22.0.0 (lts/jod)Homebrew installs it for you; with npm you install it yourself
Container runtime (Docker / Podman)See Docker belowYou install it — Docker Desktop (macOS/Windows) or Docker Engine (Linux). Solo auto-installs Podman on Linux/macOS/WSL2 if Docker Engine is not found. Not supported on native Windows.
kubectl>= v1.32.2Solo provisions it at deploy time - reuses a compatible copy already on your system, or downloads one into ~/.solo/bin
Helmv3.14.2Solo provisions it at deploy time
Kind>= v0.29.0Solo provisions it at deploy time
Kubernetes>= v1.32.2Installed automatically by Kind
k9s (optional)>= v0.27.4You install it

Note: Solo’s provisioned copies of kubectl, Kind, and Helm live in ~/.solo/bin, which is not necessarily on your PATH. If you want to run kubectl, kind, or helm commands yourself (some guides do), install kubectl, Kind, and Helm on your PATH separately.

Windows (WSL2) prerequisite

Kind (which Solo provisions automatically) requires WSL2 to be enabled on Windows, but you do not need a WSL2 Linux distro installed — only the WSL2 feature itself. Enable it with:

wsl --install --no-distribution

WSL2 requires hardware virtualization and the Virtual Machine Platform Windows feature. If virtualization is unavailable (for example, wsl --install reports HCS_E_HYPERV_NOT_INSTALLED), use the native Windows (PowerShell) path instead, which does not require WSL2.

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.

    Docker Desktop resource allocation settings

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 (natively with PowerShell, or via WSL2). Select your platform below to install the required container runtime and configure your environment, before proceeding to Quickstart:

  1. Install Homebrew (if not already installed):

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Install Docker Desktop:

    macOS prerequisite: Docker Desktop must be open before running solo one-shot single deploy. The Docker daemon is not started automatically on macOS, so confirm Docker Desktop is running from your menu bar before you begin.

  3. Install Solo:

    brew install hiero-ledger/tools/solo

  4. Verify the installation:

    solo --version

  1. Install Homebrew for Linux:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    Add Homebrew to your PATH:

    echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

  2. Install Docker Engine (for Ubuntu/Debian):

    sudo apt-get update
sudo apt-get install -y docker.io
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker ${USER}

    Log out and back in for the group changes to take effect.

  3. Install Solo:

    brew install hiero-ledger/tools/solo

  4. Verify the installation:

    solo --version

Run Solo natively from Windows PowerShell. Run every command below in a PowerShell terminal.

  1. Install Docker Desktop for Windows:

    Windows prerequisite: Docker Desktop must be running before you run solo one-shot single deploy.

  2. Install Node.js (>= 22.0.0):

    winget install OpenJS.NodeJS.LTS

    Or download the installer from nodejs.org.

  3. Install Solo via npm.

    npm installs the Solo CLI only; Solo provisions kubectl, Helm, and Kind automatically at deploy time:

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

  4. Verify the installation:

    solo --version

Note: Open a new PowerShell window after installing tools so updated PATH entries take effect.

Note: Make sure your machine meets the Windows (WSL2) prerequisite first. If WSL and a Linux distribution are already installed, skip step 1 (and you may use a distribution other than Ubuntu).

  1. Run the following command in Windows PowerShell (as Administrator), then reboot and open the Ubuntu terminal. All subsequent commands must be run inside the Ubuntu (WSL2) terminal.

    wsl --install Ubuntu

  2. Install build tools required by Homebrew:

    sudo apt-get install build-essential procps curl file git

    Note: These are the Linux prerequisites for Homebrew. Without build-essential, brew install hiero-ledger/tools/solo fails with Error: ... must be built from source. Install Clang or run brew install gcc. Only run this command on a trusted system.

  3. Install Homebrew for Linux:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    Add Homebrew to your PATH:

    echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

  4. Install Docker Desktop for Windows:

  5. Install Solo:

    brew install hiero-ledger/tools/solo

  6. Verify the installation:

    solo --version

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

Solo VersionNode.jsConsensus NodeKubernetesDocker ResourcesRelease DateEnd of Support
0.81.0>= 22.0.0 (lts/jod)v0.74.0>= v1.32.2Memory >= 12GB, CPU cores >= 62026-07-072026-08-07
0.80.0 (LTS)>= 22.0.0 (lts/jod)v0.74.0>= v1.32.2Memory >= 12GB, CPU cores >= 62026-06-302026-09-30
0.79.0>= 22.0.0 (lts/jod)v0.74.0>= v1.32.2Memory >= 12GB, CPU cores >= 62026-06-232026-07-23
0.78.0 (LTS)>= 22.0.0 (lts/jod)v0.74.0>= v1.32.2Memory >= 12GB, CPU cores >= 62026-06-162026-09-16
0.76.0 (LTS)>= 22.0.0 (lts/jod)v0.73.0>= v1.32.2Memory >= 12GB, CPU cores >= 62026-06-022026-09-02
0.74.0 (LTS)>= 22.0.0 (lts/jod)v0.73.0>= v1.32.2Memory >= 12GB, CPU cores >= 62026-05-262026-08-26
0.72.0 (LTS)>= 22.0.0 (lts/jod)v0.71.0>= v1.32.2Memory >= 12GB, CPU cores >= 62026-05-052026-08-05
0.70.0 (LTS)>= 22.0.0 (lts/jod)v0.71.0>= v1.32.2Memory >= 12GB, CPU cores >= 62026-04-282026-07-28
0.68.0 (LTS)>= 22.0.0 (lts/jod)v0.71.0>= v1.32.2Memory >= 12GB, CPU cores >= 62026-04-072026-07-07

To see a list of legacy releases, please check the legacy versions documentation page.

Troubleshooting Installation

If you experience issues installing or upgrading Solo - for example, conflicts with a previous installation - clean up your environment and reinstall:

  • To remove a legacy npm install or perform a full environment reset (delete Solo-managed Kind clusters and your ~/.solo directory), see the Cleanup guide.
  • To upgrade an existing install, install a specific version, or switch between Homebrew and npm, see Upgrading an existing Solo installation.
  • macOS “mounts denied” error on Apple Silicon: If solo one-shot single deploy fails immediately with a “mounts denied” or “path is not shared from the host” error, add /opt/homebrew to Docker Desktop’s File Sharing list: Settings → Resources → File Sharing → + → add /opt/homebrew → Apply & Restart. This can occur on Apple Silicon Macs (M1/M2/M3/M4) when Homebrew’s install path (/opt/homebrew) is not included in Docker Desktop’s shared directories. Intel Mac users (Homebrew path /usr/local) are not affected.
  • WSL2 fails to install (for example, wsl --install reports HCS_E_HYPERV_NOT_INSTALLED): WSL2 requires hardware virtualization and the Virtual Machine Platform feature. See Microsoft’s Install WSL guide, or use the native Windows (PowerShell) path, which does not require WSL2.
Last modified June 29, 2026: docs: add build-essential prerequisite to WSL2 setup tab (#216) (#242) (8e6ed36)