How to Remove a Peer

This guide shows you how to gracefully remove an agent from your Arctic cluster.

Before You Start

Understand the difference between removing a remote peer and removing the local peer:

Remote peer: Removes another agent from your view of the cluster
Local peer (remove-self): Gracefully removes the current agent from the entire cluster

Remove a Remote Peer

Use this when you want to remove another agent from your cluster.

1. Find the Peer ID

List all peers to find the ID of the peer you want to remove:

arctic peers list

2. Delete the Peer

Remove the peer by ID:

arctic peers delete PEER_ID

# You will be prompted to confirm. Use --yes to skip confirmation:
arctic peers delete PEER_ID --yes

3. Verify Removal

Confirm the peer no longer appears in the list:

arctic peers list

Remove the Local Peer (Self-Removal)

Use this when you want to gracefully remove the current agent from the cluster. This is useful when decommissioning a node.

1. Remove Self

arctic peers remove-self

# You will be prompted to confirm. Use --yes to skip confirmation:
arctic peers remove-self --yes

2. What Happens

When you remove self:

The local peer is marked as deactivated
A signed deactivation announcement is broadcast to all cluster peers
Other peers receive the announcement and remove this peer from their databases
Services involving this peer become inactive

Cleanup After Removal

After removing a peer, you may want to:

Delete Associated Services

Services involving the removed peer will no longer function. List and delete them:

# List services involving the removed peer
arctic services list --target-peer REMOVED_PEER_ID

# Delete each service
arctic services delete SERVICE_ID --yes

Update CLI Configuration

If you have the removed peer in your CLI config, remove it:

arctic config delete-peer PEER_ID_OR_NAME

Troubleshooting

Cannot Delete Local Peer

If you try to delete the local peer using peers delete:

Error: cannot delete local peer, use 'peers remove-self' instead

Use arctic peers remove-self for the local agent.

Peer Not Found

If the peer ID is not found:

Verify the peer ID: arctic peers list
The peer may have already been removed by another cluster member
Use --all-contexts to check all configured agents

Services Still Active After Removal

Services are not automatically deleted when a peer is removed. You must manually delete services that reference the removed peer.

Remove a Peer

On this page