> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Peering

> Configure seeds, persistent peers and P2P limits on a Cosmos Hub node, and run a seed node for the network.

Commands on this page were run on gaia v28.3.1 (Cosmos SDK v0.53.4, CometBFT v0.38.23) on 2026-10-15 by agent testing on a local devnet.

This page is for operators whose node finds too few peers, falls behind, or who want to run a seed node or sentry layer. It assumes gaia is installed and initialized ([Join mainnet](https://docs.cosmos.network/hub/latest/hub-tutorials/join-mainnet.md)). At the end the node keeps a stable set of inbound and outbound peers, and other nodes can find it.

## How a node finds peers

A new node needs at least one address to start from. It dials the `seeds` and receives addresses from them through peer exchange (PEX). It stores those addresses in `config/addrbook.json` and from then on dials from the address book. Entries in `persistent_peers` are dialed regardless and redialed when the connection drops. Everything is in `config.toml` under `[p2p]`. The `gaiad init` command writes these defaults:

```toml theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
[p2p]
laddr = "tcp://0.0.0.0:26656"
external_address = ""
seeds = ""
persistent_peers = ""
max_num_inbound_peers = 40
max_num_outbound_peers = 10
pex = true
seed_mode = false
```

Each peer entry has the form `<node-id>@<host>:<port>`. The node ID is the hash of the node key in `config/node_key.json`:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
gaiad comet show-node-id
```

The output is a 40 character hex string. There is no rotation for the node key. Deleting `node_key.json` and restarting generates a new one. The node then gets a new ID that other operators' `persistent_peers` entries no longer match.

## Seeds and persistent peers for cosmoshub-4

The maintained list is in the [chain registry](https://github.com/cosmos/chain-registry/blob/master/cosmoshub/chain.json) under `peers.seeds` and `peers.persistent_peers` (ten seeds and eight persistent peers on 2026-10-15). Pull the seeds from there rather than copying a list that goes stale:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl -s https://raw.githubusercontent.com/cosmos/chain-registry/master/cosmoshub/chain.json \
  | jq -r '[.peers.seeds[] | "\(.id)@\(.address)"] | join(",")'
```

Write the result into `seeds`. The `-s` flag (`--skip-validate`) is required for every `config.toml` key on v28.3.1. Without it the command fails with `cometbft config is not supported`.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
SEEDS="$(curl -s https://raw.githubusercontent.com/cosmos/chain-registry/master/cosmoshub/chain.json | jq -r '[.peers.seeds[] | "\(.id)@\(.address)"] | join(",")')"
gaiad config set config p2p.seeds "$SEEDS" -s
```

Keep `persistent_peers` short. Put your own sentries or a few nodes you trust there. A long list of public persistent peers only wastes dial attempts when they are full. Testnet seeds for chain-id `provider` are in the [cosmos/testnets provider README](https://github.com/cosmos/testnets/blob/master/provider/README.md).

## Peer limits and addresses

The defaults `max_num_inbound_peers = 40` and `max_num_outbound_peers = 10` suit a normal full node. An endpoint node that many others want to dial can raise inbound to 80 or more if it has the bandwidth. Outbound rarely needs to go above 20. Each peer costs memory and a steady few KiB/s.

The `external_address` key must be set when the node is behind network address translation (NAT) or a cloud public IP that the interface does not have. Otherwise peers receive the private address and cannot dial back:

```toml theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
external_address = "203.0.113.10:26656"
```

Open TCP 26656 inbound in the firewall. The remote procedure call (RPC) port 26657 stays closed. See [Run public endpoints](https://docs.cosmos.network/hub/latest/infrastructure/endpoints.md) for the proxy setup if the node also serves RPC.

Sentry nodes set `private_peer_ids` to the validator's node ID so the validator address is never gossiped. The validator sets `pex = false` with only its sentries in `persistent_peers`. The full layout is on [Validator security](https://docs.cosmos.network/hub/latest/validators/security.md).

## Run a seed node

A seed node answers address requests and disconnects. It does not keep peers or relay blocks. It is a normal full node with:

```toml theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
seed_mode = true
pex = true
max_num_inbound_peers = 200
```

It still needs to sync and stay synced, because it validates the addresses it hands out by having connected to them. Publish `<node-id>@<host>:26656` in the chain registry `peers.seeds` list once it has run stably. A seed that goes offline leaves every node that copied it dialing a dead address at startup. Remove the entry before decommissioning.

## Verify

Count connected peers through the local RPC:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl -s http://127.0.0.1:26657/net_info | jq '.result | {n_peers, listening, outbound: [.peers[] | select(.is_outbound)] | length}'
```

The `n_peers` count should stay near `max_num_outbound_peers` plus whatever inbound traffic arrives. The `listening` field is `true`. If `n_peers` stays at 0, the seeds entry is empty or malformed. The log line `Dialing peer` followed by `auth failure` means the node ID in an entry does not match the peer's key. The node's own ID comes from `gaiad comet show-node-id`. Compare it with what a remote operator put in their config if they cannot reach you.

## Next

* [Sync options](https://docs.cosmos.network/hub/latest/node/sync.md) if the node has peers but does not catch up.
* [Validator security](https://docs.cosmos.network/hub/latest/validators/security.md) for sentries and private peers.
* [Monitoring](https://docs.cosmos.network/hub/latest/validators/monitoring.md) for the `cometbft_p2p_peers` metric.