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.

macOS prerequisite: Docker Desktop must be installed and 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.

Apple Silicon: If solo one-shot single deploy fails with a “mounts denied” error, see Troubleshooting Installation.

Windows (PowerShell): Complete the System Readiness Windows tab first, then run the commands on this page from a PowerShell terminal. The solo and kubectl commands are identical in PowerShell; only shell-specific commands (pipes, port checks, and ~/.solo paths) differ, and those show a PowerShell tab.

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 the System Readiness.

Step 1: Install Solo CLI

Install the latest Solo CLI globally using one of the following methods:

• npm (recommended for all platforms):

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

  Note: npm requires Node.js >= 22.0.0 to already be present (check with node --version; upgrade via nvm or nodejs.org if needed — Solo will fail with an EBADENGINE warning on Node.js 20.x or earlier). Solo provisions kubectl, Helm, and Kind automatically at deploy time.

• Homebrew (deprecated — macOS/Linux/WSL2 only):

  brew install hiero-ledger/tools/solo
  

  ⚠️ Homebrew support is being deprecated. Solo will stop publishing updates to Homebrew after August 31, 2026. New users should install via npm. Existing Homebrew users should migrate before August 31.

Verify the installation

Confirm that Solo is installed and available on your PATH:

solo --version

Expected output (version may be different):

******************************* Solo *********************************************
Version			: 0.84.0
**********************************************************************************

If you see a similar banner with a valid Solo version, your installation is successful.

Step 2: 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.

⏱ First-run time: solo one-shot single deploy typically takes 3–5 minutes when container images are already cached locally, or 10–20 minutes on the very first run while Solo pulls images over the network (longer on slower connections). Long pauses with no visible output change are normal — the deploy is still running. Later deployments reuse the local image cache and complete faster. See Solo Image Cache.

Note: During deployment you may see Stopping port-forward for port [N] printed in yellow. This is expected - as it sets up the network, Solo stops and re-establishes port-forwards to finalize the port configuration (clearing stale forwards and migrating ports as needed). It does not indicate a failure.

PostgreSQL startup timeout: If the first deployment fails during mirror node setup with a PostgreSQL startup timeout, destroy the deployment and retry — this is a known intermittent issue on first deploy:

solo one-shot single destroy
solo one-shot single deploy

What gets deployed

solo one-shot multi deploy --num-consensus-nodes 3

Capture your deployment name

solo one-shot single deploy (and multi deploy) assigns a unique name to each deployment. Subsequent Solo commands and SDK guides reference it as <your-deployment-name> — substitute your actual value when you run them.

Retrieve the most recent deployment’s name with:

solo one-shot show deployment

The output includes a Deployment Name: line - use that value as <deployment-name> in other commands.

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:

• Bash
• PowerShell

kubectl get pods -A | grep -v kube-system

kubectl get pods -A | Select-String -Pattern 'kube-system' -NotMatch

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.

Step 3: 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. For the full endpoint reference — default ports for Solo 0.63+ and Solo 0.62 and earlier, verification commands, and port lookup — see Service Endpoints.

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

Step 4: Tear down your network

When you are finished, destroy the network to free up resources:

solo one-shot single destroy

For a full teardown procedure including failure recovery, see the Cleanup guide. For granular stop/start and management options, see Managing Your Network.

Next Steps

With your network running, connect your application or explore Solo further:

• Using Solo with Hiero SDKs — Submit transactions using the JavaScript, Java, or Go SDK.
• Using Solo with EVM Tools — Connect MetaMask, Hardhat, Foundry, or ethers.js to your local network.
• Managing Your Network — Stop, start, and reset nodes without redeploying.
• Service Endpoints — Quick reference for all default ports and connection details.