Skip to main content
Solo is a Kubernetes-native tool that runs a full Hedera network on your machine: consensus node, mirror node, block node, JSON-RPC relay, and the Mirror Node Explorer. This page walks through installing the CLI from npm, deploying a single-node network, and confirming that it works.
Solo is maintained by the Hiero project and its documentation is the source of truth for installation details and version-specific behavior. This page covers the setup path most Hedera developers need. See the Solo quickstart for the complete reference.

​
Prerequisites

Install the following before you begin: You do not need to install Kubernetes tooling yourself. Solo provisions kubectl, Helm, and kind at deploy time. Work through the Solo system readiness guide first if this is your first deployment on this machine.

​
Install the CLI

Confirm the install:

​
Deploy a network

Start a single-node network. This deploys the consensus node, mirror node, explorer, and JSON-RPC relay, and generates pre-funded accounts:
For a multi-node deployment, use the multi variant and set the node count:
Look up the deployment name at any time:

​
Endpoints

On Solo 0.63 and later, one-shot single deploy exposes:
These are defaults, not guarantees. Solo reaches these services through kubectl port-forward. If a port is already taken, Solo picks the next free one and logs Using available port <port> rather than failing. The actual assignments print at the end of the deploy, and you can look them up later:
Solo 0.62 and earlier use different defaults: 7546 for the relay, 50211 for consensus gRPC, 8081 for the mirror node REST API, and 8080 for the explorer.

​
Accounts and keys

Solo writes the generated accounts to:
The default deployment name is one-shot, so the default path is ~/.solo/one-shot-one-shot/accounts.json. The file has two parts:
  • systemAccounts[0] is the bootstrap operator account, 0.0.2, with an Ed25519 key in DER format. Use this as the operator for native SDK work.
  • createdAccounts holds pre-funded ECDSA accounts. Each entry has a private key (64 hex characters with a 0x prefix), its public key, and the derived EVM address. Use these for MetaMask, Hardhat, Foundry, and ethers.js. ED25519 accounts do not work over the JSON-RPC relay.
Export an ECDSA key for EVM tooling rather than hardcoding it:
The keys in a Solo deployment are development credentials generated on your machine. They exist only on your local network. Never reuse a key from any tutorial or example on testnet or mainnet.

​
Verify the network

Check that the pods are up:
Confirm the consensus node is accepting connections:
Query the mirror node REST API:
You can also open the Mirror Node Explorer at http://localhost:38080 and browse blocks, transactions, and accounts on your local network.

​
Tear down

For a multi-node deployment, use solo one-shot multi destroy.

​
Troubleshooting

A service is not on the port you expected. Solo does not fail when a default port is taken; it forwards to the next free port instead. Read the assignments printed at the end of the deploy, or run solo deployment config ports --deployment <deployment-name>. A deploy fails with ImagePullBackOff. Solo releases earlier than 0.91.0 reference an object-storage image (minio/minio) that no longer resolves from docker.io or quay.io, returning 401 UNAUTHORIZED instead. Solo deploys that component by default, so affected releases fail on a normal one-shot deploy. Solo 0.91.0 replaced the image. Upgrade to a current release, or see the Solo documentation for version-specific guidance:
Docker is not running. Solo provisions a kind cluster and requires the Docker daemon. On macOS the daemon does not start automatically, so open Docker Desktop and confirm it is running before you deploy. Stopping port-forward for port [N] appears in yellow during deploy. This is expected. Solo clears stale forwards and re-establishes them while finalizing port configuration. It does not indicate a failure. nc -zv localhost 35211 prints a connection refused line on macOS. The first line is a failed IPv6 attempt. If the second line says the connection succeeded, the port is reachable. The deployment stalls or pods stay pending. Multi-node deployments need 16 GB of RAM and 8 CPU cores allocated to Docker. Raise Docker’s resource limits, or deploy a single node instead. Port-forwards are gone after a restart. Restore them without redeploying: solo deployment refresh port-forwards --deployment <deployment-name>. For anything beyond these, see Solo troubleshooting or open an issue in the Solo repository.

​
Next steps

Point an SDK at your network

Configure the JavaScript, Java, or Go SDK against your Solo endpoints.

Using Solo with EVM tools

Connect MetaMask, Hardhat, and Foundry to the local relay.

Hardhat configuration

Hedera-specific notes for configuring Hardhat against a relay.

Foundry setup

Configure foundry.toml, deploy with forge script, and interact with cast.