Networking and Trust
Gossip, QUIC, dynamic ports, entrypoints, known validators, and genesis pinning for Agave operations.
Agave uses gossip and dynamic protocol ports to find and communicate with peers, while trust controls prevent a node from joining or repairing from the wrong cluster. Networking therefore combines public reachability with strong assumptions about cluster identity; treat port policy and peer trust as one design problem.
Deployment profiles and ports
Two reference deployment shapes use different dynamic ranges. Do not copy a range from one deployment into another without changing the corresponding firewall, NetworkPolicy, container-port, and service configuration.
| Setting | VM-oriented profile | Kubernetes-oriented profile | Purpose |
|---|---|---|---|
| Gossip port | 8001 | 8001 | Entry point for gossip discovery. |
| Dynamic port range | 8000-8020 | 8002-8030 | Range used for protocol traffic selected through --dynamic-port-range. |
| RPC port | 8899 | 8899 | HTTP JSON-RPC endpoint. |
| WebSocket port | 8900 by convention | 8900 | RPC WebSocket endpoint when exposed. |
| Faucet port | 9900 | 9900 | Optional development-token service. |
The Kubernetes-oriented profile declares TCP and UDP container ports across 8002-8030; its optional QUIC NodePort services expose only the configured TPU ports (8004 and 8010) for each node. That is an implementation choice, not proof that those two NodePorts alone cover every protocol path. Test the actual node-level path and NetworkPolicy behavior after each networking change.
The upstream Agave requirements page documents the default public validator range as TCP and UDP 8000–8030 and notes that it can be changed with --dynamic-port-range. Choose a free range once, open it consistently on every relevant firewall, and test TCP and UDP separately.
Gossip and entrypoints
The bootstrap node advertises its own gossip host/port. Followers use the bootstrap node as an entrypoint. Public-network templates include several entrypoints because a single endpoint is a weak dependency; private clusters can start with one bootstrap node but should document the recovery plan if it becomes unreachable.
Known validators
--known-validator <identity> restricts repair and snapshot trust to named validator identities. For a private cluster, include the bootstrap identity and any additional identities the cluster explicitly trusts. For public clusters, use only current values from official network guidance; they change over time.
Expected genesis hash
--expected-genesis-hash <hash> is the most important guardrail for a follower. It states exactly which network state the node expects. Capture the hash after bootstrap, distribute it with the environment configuration, and fail deployment if a new node sees another hash.
QUIC and NAT
The private service enables --tpu-use-quic. QUIC does not remove the need for a correct UDP policy. Agave’s own requirements warn that validators behind NAT need specialised troubleshooting; do not assume a Kubernetes service, consumer router, or generic cloud load balancer will transparently support the required peer-to-peer traffic.
Verification
Run these checks from both the node and an external management network. If gossip succeeds only locally, the cluster is not reachable in the way its topology claims.