LANYARDSSH AGENT SWITCHBOARD
FIELD MANUALSECTION 05 / SIGNAL FLOW

SECTION 05 / SIGNAL FLOW

Routing model

Identity discovery is broad; signing is key-specific, ordered, bounded, and adaptive.
How Lanyard routes SSH agent requestsThree agent sources converge at Lanyard, which exposes one stable socket to SSH, Git, and terminal multiplexers.FORWARDED AGENTREGISTERED AGENT1PASSWORDLANYARDTRY · PROMOTE · FAIL CLOSEDSSHGIT SIGNMUX SESSION
FIG. 01 Requests enter through one stable socket. Lanyard finds a key without making your shell remember where it lives.

Candidate order

  1. The agent that most recently completed a signature for the requested key.
  2. Explicit registrations, newest first, followed by discovered sockets in stable path order.
  3. Explicitly configured static agents, including local 1Password.

Listing identities never promotes an agent. Only a completed signature is evidence that a signer is useful right now.

Identity requests

Lanyard asks every reachable candidate, unions their public identities, and deduplicates equal keys. A slow or broken candidate cannot prevent healthy agents from contributing within the configured request budget.

Signature requests

Current candidates are tried in order; Lanyard does not cache identity-list results because agent ownership and availability can change. A timeout or ordinary agent failure advances to the next candidate. Success promotes that candidate for the exact requested public-key blob. Exhaustion returns an SSH agent failure response.

OpenSSH extensions

query and session-bind@openssh.com are understood. Session bindings are replayed to candidate agents before a signature is requested, preserving OpenSSH’s destination-bound authentication behavior. Unknown extensions fail closed.

BudgetDefault
Connect500 ms
Identity listing2 s / agent
Signing30 s / agent
Message size256 KiB
Candidates32