Validator Configuration Reference
A reviewed Agave startup-flag reference for private clusters, with the decisions each flag encodes.
Validator configuration is the complete set of startup flags and host settings that determines a node’s identity, peer trust, data retention, and RPC behavior. Keep the effective command line under configuration management and review a flag change like a production code change. This reference describes the private-cluster shape without publishing environment-specific hostnames, keys, or cluster identifiers.
Use agave-validator --help from the exact binary being deployed to validate a flag: names, defaults, and behavior can change between releases. The Agave validator setup guide is the authoritative upstream baseline for a network validator.
Common private-cluster shape
The following is a redacted, line-broken reference configuration for a VM-oriented development cluster. A Kubernetes-oriented design may use a different dynamic range, such as 8002-8030, with StatefulSets, host networking, and manifest-rendered arguments. Treat a profile as a coherent configuration, not a list of interchangeable flags.
A bootstrap node additionally has the genesis locally and avoids fetching it or a snapshot during normal startup. A follower supplies a bootstrap entrypoint, known-validator identities, and an expected genesis hash. Keep those role-specific pieces separate instead of one large command with inactive conditionals.
Identity and data paths
| Flag | Decision it encodes | Verify before start |
|---|---|---|
--identity <path> | Which key is the node’s on-network identity. | File mode/owner, expected public key, and whether the service user can read it. |
--vote-account <pubkey> | Which vote account a voting validator uses. | Account is the intended one; RPC-only nodes use --no-voting instead of an accidental vote setup. |
--ledger <dir> | Where ledger state is written. | Dedicated fast storage, free capacity, mount ownership, and recovery path. |
--accounts <dir> | Where account state is stored. | Dedicated capacity/IO budget; separate from the OS and preferably from ledger storage. |
--limit-ledger-size <value> | Local ledger retention bound. | The retention trade-off is documented and historical-RPC promises do not exceed it. |
The identity path is sensitive. The vote-account argument is a public key, but the identity keypair is private. See key hierarchy for authority placement and snapshots and restore for the retention/recovery consequence.
Network and discovery
| Flag | Decision it encodes | Failure if wrong |
|---|---|---|
--bind-address | Interface on which the node binds protocol services. | Node is unreachable or bound to an unintended network. |
--gossip-host / --gossip-port | Address peers learn for gossip. | Local process runs but peers cannot discover or reach it. |
--dynamic-port-range 8000-8020 | The finite transport range in this example. A Kubernetes-oriented profile may instead use 8002-8030. | Gossip may work while repair/TPU/TVU traffic fails. |
--rpc-port 8899 | Local HTTP RPC listener. | Health checks or a proxy target the wrong listener. |
--public-rpc-address | The advertised address when an RPC service is intended to be reachable. | Clients/peers receive an unusable or private address. |
--tpu-use-quic | QUIC transport is enabled for TPU traffic. | UDP/QUIC policy is incomplete or behavior differs from expected topology. |
--allow-private-addr | Private addressing is permitted for the development topology. | A private-network deployment may reject otherwise valid peer addresses. |
Never interpret a successful TCP test on 8899 as validation of peer-to-peer networking. Verify the bounded UDP range and gossip from the actual network locations that must reach the node. The full rationale is in networking and trust.
Cluster trust controls
Followers should carry the cluster’s trust context explicitly:
| Control | What it prevents | Change rule |
|---|---|---|
| Entrypoint | Starting peer discovery from an arbitrary endpoint. | Update through the cluster configuration, not an emergency shell edit. |
| Known validator | Trusting repair/snapshot sources outside the declared peer set. | Add/remove a public identity only with a documented ownership change. |
| Expected genesis hash | Quietly attaching a node to a different cluster. | Change only when deliberately creating/migrating to a new network. |
For bootstrap nodes, --no-genesis-fetch and --no-snapshot-fetch avoid treating the first node as a follower. Followers should have an explicit snapshot-fetch policy. Preventing a fetch is appropriate only when the recovery state is trustworthy and the recovery plan supports it.
Readiness and leader behavior
The private development profile includes --no-wait-for-vote-to-start-leader. This speeds a controlled development bootstrap, but it is not a blanket production recommendation. Record why a cluster should allow leadership before vote behavior is observed, and test the effect under the target client version.
It also includes --no-poh-speed-test, paired with a genesis configuration using --hashes-per-tick sleep. That combination is chosen to make virtualized development hardware practical; it does not prove that an underpowered production machine will perform acceptably. Measure actual slot/leader performance and host contention.
--no-os-network-limits-test suppresses a startup check. It does not tune the host. Apply and verify explicit OS settings first, then use the suppression only as a conscious profile decision. The relevant baseline is documented in storage and OS tuning.
RPC role modifiers
Add these only on an RPC role after the public contract and capacity work are approved:
| Flag | What it enables | Operational consequence |
|---|---|---|
--no-voting | Non-voting RPC operation. | Removes consensus participation; does not eliminate ledger/accounts load. |
--full-rpc-api | The complete RPC method surface. | Broader attack surface and more expensive method classes. |
--enable-rpc-transaction-history | Transaction history serving. | Retention and IO promise that must match product behavior. |
--account-index <kind> | Specific richer account query path. | Extra disk/startup/replay impact; choose from measured customer queries. |
--private-rpc | Private operational RPC behavior. | Useful for an internal endpoint, not a replacement for edge authorization. |
Do not bolt public traffic onto a bootstrap validator merely because it has --full-rpc-api. Follow validator and RPC nodes, RPC security, and capacity testing.
Snapshot and WAL choices
Snapshot cadence, retention, and startup-fetch flags are recovery controls, not incidental defaults. This development example uses --full-snapshot-interval-slots 500; a conservative local retention policy may keep one full and two incremental snapshots. Size these values from RPO, RTO, available disk, and measured replay time.
Some deployment templates may include a WAL recovery mode such as skip_any_corrupted_record. Treat that as a version-specific recovery decision with an explicit incident record, not a generic availability switch. If corruption is suspected, preserve evidence and consult the exact binary’s supported options before changing a ledger in place.
Effective-configuration evidence
At each deployment/restart, retain an auditable record containing:
- Agave version and binary provenance.
- Full effective command with private paths, secrets, and host-specific values redacted.
- Configuration revision, systemd unit revision, and host/kernel baseline.
- Node identity public key, vote account public key where applicable, intended genesis hash, entrypoints, and known validators.
- Ledger/accounts/snapshot mount identifiers and available capacity.
- Pre/post checks for genesis, version, slot progression, vote status, and RPC exposure.
This record makes configuration drift discoverable without putting private key material into a ticket, pastebin, or public documentation.