Private Cluster Topology

How the bootstrap node, followers, genesis, faucet, and trust boundaries fit together in a private Agave cluster.

A private Solana cluster is an independently operated network whose validators agree on a dedicated genesis and controlled peer set. It is not “one validator with an RPC port”: it has a bootstrap authority, follower nodes, a controlled token source, and a deliberately small trust boundary.

Reference implementation

The Agave private-devnet role implements this bootstrap-and-follower model for host-based deployments. It prepares nodes, creates genesis on the bootstrap node, configures followers, and can run a bounded faucet. For Kubernetes deployments, supply environment-specific configuration and any persistent keys through your own secret-management path.

Roles

Role	Responsibility	State it owns
Bootstrap validator	Creates genesis, starts the initial cluster, and provides the first trusted gossip endpoint.	Genesis ledger, bootstrap identity/vote/stake keys, and the public faucet configuration.
Follower validator	Joins the known cluster and validates/participates according to its role.	Its own identity and data directories; never the bootstrap private keys.
Faucet	Distributes development tokens under explicit limits.	Faucet keypair and request-rate policy; in Kubernetes, run it as a separate Deployment with a dedicated Secret.
Operator workstation	Creates custody-sensitive keys and performs high-trust account operations.	Withdraw and stake authority material where applicable.

Bootstrap flow

Prepare directories for configuration, ledger, and accounts under a dedicated service account.
Create or restore bootstrap identity, vote, stake, and faucet keypairs.
Fetch the core and SPL programs required at genesis.
Run solana-genesis once and preserve the resulting genesis hash.
Start the bootstrap validator with --no-genesis-fetch and --no-snapshot-fetch; it must use the local genesis it created.
Verify cluster version, advancing slots, and validator visibility before allowing followers to join.

Follower flow

A follower points to the bootstrap gossip address, uses a configured dynamic UDP range, and should pin the expected genesis hash when it is known. Configure the bootstrap identity as a known validator. This protects the follower from joining a network that only happens to be reachable at the configured address.

operator keys ──> bootstrap genesis ──> bootstrap gossip/RPC
                                         │
                                         ├──> follower A (own identity + expected genesis)
                                         ├──> follower B (own identity + expected genesis)
                                         └──> optional faucet

State locations

Keep configuration, ledger, and accounts directories separate in the service definition and filesystem layout. A reset that removes only one directory can leave a node with incompatible remnants of a prior cluster.

Reset decision

There are two very different operations:

Restart: retain genesis, ledger, keys, and cluster identity.
New network: stop services, preserve evidence as needed, intentionally wipe state, generate a new genesis, and distribute the new hash.

Never call a state wipe “troubleshooting” without making it explicit that it creates or requires a new network identity.