LANYARDSSH AGENT SWITCHBOARD
FIELD MANUALSECTION 09 / INTERNALS

SECTION 09 / INTERNALS

Architecture

A protocol-aware functional core describes routing decisions; a narrow asynchronous shell owns Unix sockets, clocks, and upstream I/O.
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.

Two socket faces

The agent socket exposes the OpenSSH agent protocol. A sibling control socket exposes registration and status operations to the CLI. Keeping control messages out of the agent protocol makes both boundaries smaller and easier to test.

Functional core

Candidate ordering, identity deduplication, key-to-agent routing, promotion, and failure transitions are deterministic values. The core describes the next effect; it does not open sockets or read time.

Imperative shell

The Tokio-based shell accepts connections, applies bounded timeouts, interprets core effects, and translates I/O failures into explicit domain outcomes. Upstream tasks are isolated so one broken socket does not poison the listener.

State lifecycle

  1. Configuration establishes static candidates.
  2. Discovery and control registration add ephemeral candidates.
  3. Identity results build a deduplicated routing view.
  4. Successful signatures promote candidates in memory.
  5. Service restart safely reconstructs state; no secret or key data is persisted.

Decision records

The architecture is constrained by published records for the functional core boundary, signing failover policy,Home Manager integration, and release state machine. Revisit them when upstream protocol behavior or the runtime model changes.

Read the complete architecture decision log →