Agent & macOS Keychain

~15 min · addkeystoagent, usekeychain, macos, passphrase

Level 0Pinger

0 XP0/101 lessons0/12 achievements

0/150 XP to next level150 XP to go0% complete

Type your passphrase exactly once, ever

The combo that makes daily SSH friction-free on macOS:

AddKeysToAgent yes — when you use a key, auto-add it to ssh-agent.
UseKeychain yes — store the passphrase in the system Keychain so it survives reboots.
Default IdentityFile — so SSH knows which key to use without flags.

First connection after you set this up: SSH prompts once for the passphrase, stores it in Keychain, adds the key to the agent. Every connection after that — across reboots, across reinstalls — no passphrase prompt. The agent and Keychain handle it all.

Cross-platform caveat

UseKeychain is macOS-only. On Linux, it's an unknown directive and triggers a parse error. If you share ~/.ssh/config across both, wrap the macOS-specific lines so Linux ignores them gracefully.

Code

The clean macOS setup·ssh-config

Host *
    AddKeysToAgent yes
    UseKeychain yes
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

Cross-platform — Linux ignores UseKeychain·ssh-config

# Tell SSH to silently ignore unknown directives
IgnoreUnknown UseKeychain

Host *
    AddKeysToAgent yes
    UseKeychain yes
    IdentityFile ~/.ssh/id_ed25519

External links

Apple: Use ssh-agent in Keychain

Exercise

Set up the clean macOS setup block above. SSH into one host you've connected to before — you'll be asked for the passphrase one last time. Reboot. SSH again — no passphrase, no agent setup, instant connection. That's the muscle memory you want.