// macos

Save your SSH key passphrase in the macOS Keychain

A passphrase protects your key if your files leak. Keychain means you only type it once. Here's the setup for current macOS, and how to keep the same config working on Linux.

Updated · 2 min read · by Pixel Worship, LLC

#1. Store the passphrase once

Terminal
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

You'll be asked for the passphrase one last time. It's saved in your login Keychain and the key is loaded into ssh-agent.

On older macOS versions this was ssh-add -K. Those flags were renamed to --apple-use-keychain and --apple-load-keychain.

#2. Make SSH use it automatically

The agent starts empty after every restart. Tell SSH to read passphrases from the Keychain and load keys on first use:

~/.ssh/config
Host *
  AddKeysToAgent yes
  UseKeychain yes

Put this at the end of ~/.ssh/config: for these options, SSH uses the first value it finds. See how ~/.ssh/config is read.

#3. Check it works

After a restart, connect once (for example ssh -T git@github.com) without being asked for a passphrase, then:

Terminal
ssh-add -l
Output
256 SHA256:Zp7Lm2Qx9Ws4Rt1Yv8Nb3Hc6Jk0Uf5Ge2Da7Ti9Oq1 you@example.com (ED25519)

#Sharing your config with Linux

UseKeychain only exists in Apple's OpenSSH. On Linux it's a fatal "Bad configuration option". Tell other systems to skip it:

~/.ssh/config
Host *
  IgnoreUnknown UseKeychain
  AddKeysToAgent yes
  UseKeychain yes

IgnoreUnknown must come before the option it ignores.

#Removing a saved passphrase

Terminal
ssh-add -d --apple-use-keychain ~/.ssh/id_ed25519

#Changing the passphrase

Terminal
ssh-keygen -p -f ~/.ssh/id_ed25519
ssh-add --apple-use-keychain ~/.ssh/id_ed25519   # store the new one

#The one-checkbox version

When you create a key in EasySSHConfig, "Remember passphrase in Keychain" runs ssh-add --apple-use-keychain for you. A single setting adds the AddKeysToAgent / UseKeychain defaults. Changing a passphrase in the app updates the Keychain too.

Frequently asked questions

What replaced ssh-add -K on macOS?

ssh-add --apple-use-keychain. The old -K and -A flags were renamed to --apple-use-keychain and --apple-load-keychain.

Why does my Mac ask for the SSH passphrase after every restart?

The agent starts empty after a reboot. Add UseKeychain yes and AddKeysToAgent yes to ~/.ssh/config so SSH reads the passphrase from Keychain and loads the key on first use.

Will UseKeychain break my config on Linux?

Linux OpenSSH doesn't know the option and errors. Put IgnoreUnknown UseKeychain before it, or only use the option on your Mac.

How do I remove a saved SSH passphrase from Keychain?

Run ssh-add -d --apple-use-keychain ~/.ssh/your_key, which removes the key from the agent and its passphrase from the Keychain.