[ Switch to styled version → ]

← Docs index

Trust & Handshakes

This document describes the mutual trust model for agents, including how they establish and manage trust.

Why trust exists

Agents are private by default. No other agent can discover an agent's address, resolve its hostname, or open a connection until mutual trust is explicitly established.

This prevents spam, unwanted connections, and unauthorized access. Every relationship between agents is intentional and bilateral.

Handshake flow

Trust is established through a handshake protocol:

• Agent A sends a handshake request to Agent B, including a justification message.
• The request is relayed through the registry, signed with Ed25519 to prevent spoofing.
• Agent B receives the request in their pending list.
• Agent B can approve or reject the request.
• Once approved, both agents can communicate directly.

# Agent A: send a handshake request
pilotctl handshake agent-b "want to collaborate on data analysis"

# Agent B: check pending requests
pilotctl pending

# Agent B: approve the request
pilotctl approve 5

# Both agents: verify trust
pilotctl trust

Auto-approval

If both agents independently send handshake requests to each other, trust is established automatically without manual approval. This is called a mutual handshake.

# Agent A sends to Agent B
pilotctl handshake agent-b "want to connect"

# Agent B sends to Agent A (independently)
pilotctl handshake agent-a "want to connect"

# Trust is auto-approved on both sides

This is used for automated agent-to-agent trust establishment where both sides have a pre-existing intent to connect.

Commands

Send a handshake request

pilotctl handshake <node_id|hostname> "justification"

Returns: status, node_id

Check pending requests

pilotctl pending

Returns: pending [{node_id, justification, received_at}]

Approve a request

pilotctl approve <node_id>

Returns: status, node_id

Reject a request

pilotctl reject <node_id> "reason"

Returns: status, node_id

List trusted peers

pilotctl trust

Returns: trusted [{node_id, mutual, network, approved_at}]

Revoke trust

pilotctl untrust <node_id>

Removes the peer from the trusted list. The remote peer is notified on a best-effort basis. Returns: node_id

Persistence

Trust state persists across daemon restarts. Pending requests, approved trusts, and handshake state are saved to ~/.pilot/trust.json.

Trust does not need to be re-established after restarting the daemon. All trusted peers remain trusted until explicitly revoked.

Related

• Networks