How to Add a Peer

This guide shows you how to add a new Arctic agent to an existing cluster.

Before You Start

Ensure you have:

• An existing Arctic cluster with at least one bootstrapped agent
• A new agent that is running and accessible
• The new agent bootstrapped with the same license as your cluster
• Network connectivity between the existing cluster and the new agent

Steps

1. Bootstrap the New Agent

If the new agent has not been bootstrapped yet, initialize it with your license:

arctic bootstrap \
  --url http://NEW_AGENT_IP:8080 \
  --license-file license.json \
  --name "New Agent"

2. Verify the New Agent is Healthy

Confirm the agent is running and ready:

curl http://NEW_AGENT_IP:8080/livez

Expected response: {"status":"ok",...}

3. Add the Peer

From your CLI (configured to connect to an existing cluster agent), add the new peer:

arctic peers add NEW_AGENT_IP:8080

4. Verify the Peer Was Added

List all peers to confirm the new agent appears:

arctic peers list

The new peer should appear in the list with LOCAL: false.

What Happens During Peer Addition

When you add a peer, Arctic performs these steps:

1. Identity Exchange: The existing agent contacts the new agent and they exchange public keys
2. Signature Verification: Both agents verify the signatures match their shared license
3. Database Update: Both agents store each other's peer information
4. Gossip Initialization: The agents begin exchanging heartbeats and will synchronize state

The entire process typically completes within seconds.

Troubleshooting

Handshake Failed: Connection Refused

The new agent is not accessible. Check:

• Network connectivity: curl http://NEW_AGENT_IP:8080/livez
• Firewall rules allow port 8080
• The agent service is running: systemctl status arctic-agent

Handshake Failed: License Mismatch

The agents have different licenses. Verify:

• Both agents were bootstrapped with the same license file
• Check license IDs: arctic license show on both agents

Peer Already Exists

The peer is already in the cluster. This can happen if:

• You previously added this peer
• Another cluster member already discovered this peer via gossip

Use arctic peers list to see existing peers.

Node Limit Exceeded

Your license has a maximum node limit. Check your license:

arctic license show

Contact your administrator to upgrade your license if needed.

Related

• Remove a Peer
• Update Peer Metadata
• Clustering Concepts