Clusters & Networks
Solana runs multiple clusters - independent blockchains with their own validator sets, genesis hashes, and token economics. Picking the right cluster keeps your development safe and predictable.
Recipe
Quick-reference recipe card - copy-paste ready.
# Point CLI at a cluster
solana config set --url devnet
solana config set --url https://api.mainnet-beta.solana.com
# Verify current cluster
solana config get
# Start a local Agave 4.1.1 validator
solana-test-validator --resetWhen to reach for this:
- Bootstrapping a new project on devnet with free test SOL
- Running integration tests against a local validator
- Deploying a program to mainnet-beta for production
- Debugging transaction failures in an isolated environment
- Matching your RPC URL to the cluster where accounts were created
Working Example
#!/bin/bash
# devnet-workflow.sh - Solana CLI 3.0.10
set -e
# 1. Configure devnet
solana config set --url devnet
echo "Cluster: $(solana config get | grep 'RPC URL')"
# 2. Create a dev wallet
solana-keygen new --no-bip39-passphrase -o ./dev-keypair.json --force
PUBKEY=$(solana-keygen pubkey ./dev-keypair.json)
echo "Wallet: $PUBKEY"
# 3. Fund from faucet
solana airdrop 2 ./dev-keypair.json
solana balance ./dev-keypair.json
# 4. Verify genesis matches devnet
solana genesis-hash
# devnet genesis: EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBGimport { createSolanaRpc } from "@solana/kit";
// RPC URL must match the cluster where your accounts live
const devnet = createSolanaRpc("https://api.devnet.solana.com");
const mainnet = createSolanaRpc("https://api.mainnet-beta.solana.com");
const { value: version } = await devnet.getVersion().send();
console.log("Agave version:", version["solana-core"]);What this demonstrates:
- CLI
config set --urldetermines where all subsequent commands send transactions - Airdrops only work on devnet/testnet - not mainnet-beta
- Genesis hash uniquely identifies a cluster - mismatched RPC means missing accounts
- Kit RPC clients are cluster-specific - instantiate one per environment
Deep Dive
How It Works
- Each cluster has its own genesis block, validator set, and ledger history
- Transactions signed for one cluster are invalid on another (different recent blockhash)
- Program IDs can differ across clusters if deployed separately
- Public RPC endpoints are rate-limited; production apps use dedicated providers
Clusters at a Glance
| Cluster | Purpose | SOL | Airdrop | Stability |
|---|---|---|---|---|
| devnet | App development | Test (no value) | Yes | Moderate |
| testnet | Validator/protocol testing | Test | Yes | Lower |
| mainnet-beta | Production | Real value | No | Highest |
| localnet | Local solana-test-validator | Unlimited local | N/A | You control it |
Local Validator Options
# Fresh ledger, default ports
solana-test-validator --reset
# Clone a mainnet program for local testing
solana-test-validator --clone-upgradeable-program <PROGRAM_ID> --url mainnet-beta
# Point CLI at local validator
solana config set --url http://127.0.0.1:8899Rust Notes
// In tests, use LiteSVM 0.6.x or Surfpool 0.12.0 for programmatic local clusters
// Anchor test with Surfpool:
// [scripts]
// test = "npx surfpool run anchor test"Gotchas
- Wrong RPC for existing accounts - devnet keypairs have zero balance on mainnet. Fix: match RPC URL to where accounts were created.
- Using mainnet keys on devnet - safe, but reverse is catastrophic. Fix: use separate keypair files per cluster; never airdrop on mainnet.
- Hardcoded program IDs across clusters - deployed addresses differ per cluster. Fix: use environment config or
declare_id!per deployment. - Public RPC rate limits - devnet airdrops and heavy reads get throttled. Fix: use a dedicated RPC provider or local validator for CI.
- Testnet instability - breaks more often than devnet. Fix: use devnet for app dev, testnet only for validator work.
- Genesis hash mismatch in CI - stale validator image vs expected cluster. Fix: pin Agave 4.1.1 and verify genesis in test setup.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
solana-test-validator | Full local control, fast iteration | You need mainnet program state |
| Surfpool 0.12.0 | Anchor integration tests with fixtures | One-off CLI experiments |
| LiteSVM 0.6.x | Unit tests without a full validator | Testing network-level behavior |
| Devnet | Shared public sandbox | Load testing or guaranteed uptime |
FAQs
What is the difference between devnet and testnet?
Devnet is for application developers. Testnet is for validator and protocol testing. Devnet is more stable for day-to-day app work.
Can I use the same keypair on all clusters?
Yes - keypairs are cluster-agnostic. But account state (balances, programs) is per-cluster.
How do I get test SOL on devnet?
solana airdrop 2Limited to a few SOL per request. Use web faucets if rate-limited.
What RPC URL should I use for mainnet?
Public: https://api.mainnet-beta.solana.com. Production apps should use a dedicated provider (Helius, Triton, QuickNode, etc.).
How do I verify which cluster I am connected to?
solana genesis-hash
solana cluster-versionDoes localnet persist state between restarts?
Only if you omit --reset. With --reset, the ledger starts fresh each time.
Can I clone mainnet accounts to localnet?
Yes, with solana-test-validator --clone <PUBKEY>. Useful for testing against real program deployments.
Why do my transactions fail after switching clusters?
Recent blockhashes are cluster-specific. Fetch a new blockhash from the target cluster's RPC.
Is devnet SOL worth anything?
No. It has no market value and can be minted freely via airdrops.
What Agave version runs on public clusters?
Public clusters track stable Agave releases. Pin your local tooling to Agave 4.1.1 to match this documentation.
Should CI use devnet or localnet?
Localnet (Surfpool or solana-test-validator) is faster and free of rate limits. Use devnet only for occasional integration smoke tests.
How do explorers know which cluster to show?
Pass ?cluster=devnet or ?cluster=mainnet-beta in the URL. Default is mainnet-beta.
Related
- Solana Basics - first steps on devnet
- Wallets & Explorers - devnet workflow and faucets
- Keypairs & Addresses - per-cluster key management
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.