Skip to main content

​
Quickstart

This guide will get you up and running with a local Agave test validator in minutes. You’ll install the Agave software, start a single-node test cluster, and verify it’s working correctly.

​
What is a Test Validator?

The solana-test-validator is a full-featured, single-node cluster that runs on your local machine. It’s perfect for development because it provides:
  • No RPC rate limits
  • No airdrop limits
  • Direct on-chain program deployment
  • Configurable settings for testing different scenarios
The test validator is for development only. For production validators, see the validator setup guide.

​
Prerequisites

Before starting, ensure you have:
  • A supported operating system (Ubuntu, macOS, Fedora, or Windows)
  • At least 8GB of RAM
  • 10GB of free disk space
  • Internet connection for downloading packages

​
Installation and Setup

1

Install Agave

Install the Agave release using the official installer:macOS & Linux:
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"
Windows (Command Prompt as Administrator):
cmd /c "curl https://release.anza.xyz/stable/agave-install-init-x86_64-pc-windows-msvc.exe --output C:\agave-install-tmp\agave-install-init.exe --create-dirs"
C:\agave-install-tmp\agave-install-init.exe stable
If prompted, update your PATH environment variable by copying and running the recommended command.
For other installation methods including building from source, see the Installation guide.
2

Verify installation

Confirm Agave is installed correctly:
solana --version
You should see output like:
solana-cli 2.1.0 (src:00000000; feat:1234567890)
3

View test validator options

Before starting the validator, explore available configuration options:
solana-test-validator --help
This shows all available flags and settings. Common options include:
  • --ledger - Specify ledger storage location
  • --slots-per-epoch - Configure epoch length
  • --limit-ledger-size - Control transaction history retention
  • --bpf-program - Deploy programs at startup
4

Start the test validator

Start the test validator with default settings:
solana-test-validator
You’ll see status information printed to the console:
Ledger location: test-ledger
Log: test-ledger/validator.log
Identity: EPhgPANa5Rh2wa4V2jxt7YbtWa3Uyw4sTeZ13cQjDDB8
Genesis Hash: 4754oPEMhAKy14CZc8GzQUP93CB4ouELyaTs4P8ittYn
Version: 2.1.0
Shred Version: 13286
Gossip Address: 127.0.0.1:1024
TPU Address: 127.0.0.1:1027
JSON RPC URL: http://127.0.0.1:8899
⠈ 00:00:15 | Processed Slot: 125 | Confirmed Slot: 125 | Finalized Slot: 93 | Snapshot Slot: 0 | Transactions: 125 | ◎499.974295000
Leave the validator running in this terminal. The validator continues to process slots and update its status in real-time.
The test validator stores its ledger in the test-ledger directory. This can grow large over time. Use --limit-ledger-size to control size or delete the directory to reset the validator.

​
Interacting with Your Test Validator

Once your test validator is running, open a new terminal to interact with it using the Solana CLI tools.
1

Configure CLI to use local cluster

Set the CLI to target your local test validator:
solana config set --url http://127.0.0.1:8899
Expected output:
Config File: /home/user/.config/solana/cli/config.yml
RPC URL: http://127.0.0.1:8899
WebSocket URL: ws://127.0.0.1:8900/ (computed)
Keypair Path: /home/user/.config/solana/id.json
Commitment: confirmed
2

Verify connection

Verify you’re connected to your local test validator by checking the genesis hash:
solana genesis-hash
The output should match the Genesis Hash displayed by your running test validator.
3

Create a wallet (if needed)

If you don’t have a wallet yet, create one:
solana-keygen new
Follow the prompts to create a new keypair. You can add a passphrase for security or press Enter to skip.
This creates a file-based wallet. Never use this wallet for real funds on mainnet. For production use, use a hardware wallet.
4

Check your wallet balance

Check your wallet’s SOL balance:
solana balance
If this is a new wallet, you’ll see 0 SOL.
5

Airdrop test SOL

Request test SOL from the local faucet:
solana airdrop 10
Verify the airdrop:
solana balance
You should now see:
10 SOL
On the local test validator, you can airdrop as much SOL as you need. There are no limits!
6

Perform a test transaction

Test that transactions work by transferring SOL to the validator’s identity address (shown in the test validator output):
solana transfer <VALIDATOR_IDENTITY_ADDRESS> 1
For example:
solana transfer EPhgPANa5Rh2wa4V2jxt7YbtWa3Uyw4sTeZ13cQjDDB8 1
You’ll see confirmation of the transaction:
Signature: 5j7s6jpP8CSQhTVGWBqW7Z...

​
Understanding the Status Output

The test validator displays real-time status information: 
⠈ 00:36:02 | Processed Slot: 5142 | Confirmed Slot: 5142 | Finalized Slot: 5110 | Snapshot Slot: 5100 | Transactions: 5142 | ◎499.974295000
Here’s what each field means:
  • 00:36:02 - Session running time
  • Processed Slot - Latest slot processed by the validator
  • Confirmed Slot - Latest slot at “confirmed” commitment level
  • Finalized Slot - Latest slot at “finalized” commitment level
  • Snapshot Slot - Slot height of the last snapshot
  • Transactions - Total number of transactions processed
  • ◎499.97… - Voting authority balance in SOL
Solana has three commitment levels: processed, confirmed, and finalized. Higher commitment levels provide stronger guarantees but take slightly longer.

​
Additional Commands

​
Monitor Program Logs

Watch real-time logs from on-chain programs: 
solana logs
This is useful when developing programs - you’ll see msg!() output from your programs here.
Run this command before executing transactions you want to monitor. It needs to be running when the transaction executes.

​
Check Validator Status

Get detailed information about the validator: 
solana cluster-version
solana gossip

​
View Transaction History

See recent transactions for an address: 
solana transaction-history <ADDRESS>

​
Stopping the Test Validator

When you’re done:
  1. Switch to the terminal running the test validator
  2. Press Ctrl+C to stop it
The ledger data is saved in the test-ledger directory. To start fresh next time, delete this directory: 
rm -rf test-ledger

​
Advanced Configuration

​
Custom Ledger Location

Store the ledger in a specific location: 
solana-test-validator --ledger /path/to/ledger

​
Limit Ledger Size

Control how much transaction history is kept: 
solana-test-validator --limit-ledger-size 10000

​
Configure Epoch Length

Change how many slots per epoch: 
solana-test-validator --slots-per-epoch 100

​
Deploy Programs at Startup

Load existing programs when starting: 
solana-test-validator --bpf-program <PROGRAM_ID> <PROGRAM_SO_PATH>

​
Clone Accounts from Devnet

Copy accounts from a public cluster: 
solana-test-validator --clone <ADDRESS> --url https://api.devnet.solana.com

​
Troubleshooting

​
Port Already in Use

If port 8899 is already in use: 
solana-test-validator --rpc-port 8900
Then configure the CLI: 
solana config set --url http://127.0.0.1:8900

​
Ledger Directory Issues

If the validator fails to start, try removing the old ledger: 
rm -rf test-ledger
solana-test-validator

​
“No such file or directory” When Checking Balance

This means your wallet doesn’t exist yet. Create it with: 
solana-keygen new

​
Next Steps

CLI Introduction

Learn more about CLI conventions and commands

Choose a Cluster

Connect to devnet, testnet, or mainnet-beta

Validator Anatomy

Understand the validator architecture

Run a Production Validator

Set up a validator for testnet or mainnet