Agave Client
Agave 4.1.1 is Anza's Solana validator client - the mainline implementation for voting, ledger replay, and RPC. Run it when operating a standard staking validator or private RPC node.
Recipe
Quick-reference recipe card - copy-paste ready.
agave-install init 4.1.1
agave-validator --ledger /mnt/ledger \
--identity ~/.config/solana/identity.json \
--vote-account <VOTE_ACCOUNT_PUBKEY> \
--rpc-port 8899 \
--full-rpc-api \
--no-voting # omit --no-voting for validators that voteWhen to reach for this:
- Operating a mainnet-beta voting validator.
- Running dedicated RPC for your organization.
- Staying on Anza-supported release channel.
- Baseline before evaluating Frankendancer hybrid.
Working Example
#!/usr/bin/env bash
# Minimal Agave validator startup (adjust paths)
LEDGER=/mnt/nvme/ledger
ACCOUNTS=/mnt/nvme/accounts
IDENTITY=~/.config/solana/identity.json
VOTE_ACCOUNT=Vote111111111111111111111111111111111111111
mkdir -p "$LEDGER" "$ACCOUNTS"
agave-validator \
--ledger "$LEDGER" \
--accounts "$ACCOUNTS" \
--identity "$IDENTITY" \
--vote-account "$VOTE_ACCOUNT" \
--known-validator <TRUSTED_ENTRYPOINT> \
--entrypoint entrypoint.mainnet-beta.solana.com:8001 \
--expected-genesis-hash <MAINNET_GENESIS_HASH> \
--full-rpc-api \
--rpc-bind-address 127.0.0.1 \
--rpc-port 8899 \
--dynamic-port-range 8000-8020 \
--limit-ledger-size 50000000What this demonstrates:
- Ledger and accounts on fast NVMe paths.
--vote-accountenables consensus voting (omit for RPC-only with--no-voting).- Entrypoints and genesis hash pin network to mainnet-beta.
Deep Dive
How It Works
- Agave replays blocks, executes transactions on Sealevel SVM.
- Tower BFT tracks votes in vote account.
- Banking stage schedules transactions from TPU ingress.
- RPC serves HTTP/WebSocket APIs when
--full-rpc-apienabled.
Key Flags
| Flag | Purpose |
|---|---|
--ledger | Block store path |
--accounts | Accounts DB path |
--vote-account | On-chain vote pubkey |
--no-voting | RPC node without voting |
--limit-ledger-size | Disk cap pruning |
bash Notes
agave-validator --ledger /mnt/ledger monitor # watch catchup
solana catchup --our-localhostGotchas
- Slow disk - HDD ledger causes delinquency. Fix: NVMe for ledger + accounts; see hardware page.
- Wrong genesis hash - Node refuses to join cluster. Fix: Use official mainnet genesis from docs.
- Identity on hot laptop - Key theft risks stake. Fix: Hardware security module for mainnet keys.
- Unbounded ledger - Disk full crash. Fix:
--limit-ledger-size+ monitoring. - Public RPC without firewall - Abuse and resource drain. Fix: Bind RPC to localhost or rate-limit proxy.
- Version drift - Missing cluster upgrade. Fix: Subscribe to Anza release notes; staged restarts.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| Frankendancer hybrid | Max performance | Early setup simplicity |
| Jito-Solana | MEV infrastructure | Non-MEV operator preference |
| Hosted validator | No ops team | Full self-custody requirement |
FAQs
agave vs solana CLI naming?
Agave is validator client; Solana CLI 3.0.10 remains operator tooling from Anza distribution.
RPC-only node?
Run with --no-voting and omit vote account requirement - still syncs full ledger.
How to upgrade Agave?
Stop validator, agave-install init <version>, restart with same ledger path after backup.
Catchup taking long?
New machine or snapshot restore - use --only-known-rpc bootstrap or official snapshots.
Multiple validators per host?
Discouraged on mainnet - resource contention; separate hardware per vote account.
SWQoS requirements?
Stake on vote account improves scheduling - see SWQoS page.
Log location?
Default stderr; redirect to journald or file for monitoring stack.
Devnet validator?
Same flags with devnet entrypoints and genesis - fund vote account on devnet first.
Agave 4.1.1 pin?
Match manifest pin across CLI, validator, and local test-validator in CI.
DoubleZero?
Optional networking layer for validator interconnect - see hardware page.
Related
- Validator Basics - roles overview
- Hardware & Networking - sizing
- Vote Accounts & Staking - vote setup
- Monitoring & Epoch Ops - ops
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.