I use public key authentication on every machine I administer, and my private SSH keys are protected with strong passphrases. Without an SSH agent, you’d have to enter the passphrase every time you use a key, which quickly becomes unbearable.

Modern operating systems have agents that unlock SSH keys at login and hold them in memory for the session. Here’s how to set this up on both GNOME (Linux) and macOS.

GNOME Keyring (Linux) Link to heading

GNOME’s Keyring daemon acts as an SSH agent. To register a key so it’s unlocked at login, use ssh-add:

ssh-add ~/.ssh/your-private-key

You’ll be prompted for the key’s passphrase, which gets stored in the GNOME Keyring. After this, the key is available automatically each time you log in to your GNOME session.

GNOME Keyring supports ed25519 keys in addition to RSA from GNOME 3.28 onwards. Ed25519 is the preferred key type; if you’re still on RSA, consider generating an ed25519 key.

macOS Keychain Link to heading

macOS integrates SSH key management with the system Keychain. To add a key:

ssh-add --apple-use-keychain ~/.ssh/your-private-key

Updated 2026: The -K flag (used in the original post) was deprecated in macOS Monterey (12.0) and removed in macOS Sonoma (14.0). Use --apple-use-keychain instead. On older macOS versions, -K still works.

Starting with macOS Sierra, you also need to tell SSH to use the Keychain and load your keys automatically. Add this to your ~/.ssh/config:

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

Sharing ~/.ssh/config between Linux and macOS Link to heading

If you keep ~/.ssh/config in a dotfiles repository and use it on both Linux and macOS, you’ll hit a problem: UseKeychain is a macOS-only option. On Linux, SSH doesn’t recognize it and prints an error.

The fix is IgnoreUnknown, which tells SSH to silently ignore any options it doesn’t recognize:

Host *
  IgnoreUnknown UseKeychain
  UseKeychain yes
  AddKeysToAgent yes
  IdentityFile ~/.ssh/id_ed25519
  IdentityFile ~/.ssh/id_rsa
  Compression yes
  ControlMaster auto

IgnoreUnknown UseKeychain must appear before UseKeychain yes; SSH processes the file top to bottom, so the directive needs to be declared before the unknown option it covers.

With this config, the same file works on both platforms: Linux ignores UseKeychain, macOS uses it.