WardtermSSH client
EN
Download

How to add an SSH key to ssh-agent and the macOS Keychain

Add AddKeysToAgent yes and UseKeychain yes to ~/.ssh/config, then run ssh-add --apple-use-keychain ~/.ssh/id_ed25519 once and type the passphrase. It is saved in your login Keychain, and ssh loads it into the agent when needed, including after a restart. The old -K and -A flags are now named --apple-use-keychain and --apple-load-keychain.

Updated . ssh-add -l, -d, -t and -D, AddKeysToAgent, and IdentitiesOnly with a public key file were run with the OpenSSH 10.3 included in macOS, using throwaway keys without a Keychain entry.

Set up your ssh config

Add this to ~/.ssh/config:

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519
  • UseKeychain yes looks up the passphrase in your Keychain when a key is used, and saves it there after you type it correctly.
  • AddKeysToAgent yes adds the key to the running agent the first time it is used, so it stays unlocked for later connections.
  • IdentityFile names the key. Without this line, ssh still tries the default names.

A key file without a passphrase has nothing to store. If yours has none, add one with ssh-keygen -p -f ~/.ssh/id_ed25519 first.

No key yet? See how to generate an Ed25519 SSH key, and set a passphrase when asked.

Save the passphrase

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

Type the passphrase once. Then check that the agent holds the key:

ssh-add -l

It lists the fingerprint of each loaded key, and says The agent has no identities. if there are none.

You do not need to start the agent yourself. On macOS, launchd starts ssh-agent on demand for your session, and SSH_AUTH_SOCK already points to it. Do not add eval "$(ssh-agent)" to your shell profile: that starts a separate agent in each shell.

After a restart

The agent starts empty after a restart, but the passphrase is still in the Keychain. With the config above, your first ssh connection reads it from there and loads the key into the agent. To load every saved key at once instead:

ssh-add --apple-load-keychain

Apple changed this behavior in macOS 10.12.2. Older instructions may assume keys load by themselves. If you are asked for the passphrase again and again, check that AddKeysToAgent yes and UseKeychain yes are both set.

The old -K and -A flags

Older guides use ssh-add -K and ssh-add -A. Apple's manual page says they were renamed to --apple-use-keychain and --apple-load-keychain. They still work in some cases, but in standard OpenSSH -K means something else, related to hardware keys. Use the long names.

If you use another ssh on the same Mac

UseKeychain exists only in the ssh that Apple ships. Other builds, such as one from Homebrew or the one on a Linux machine sharing your dotfiles, stop with this error:

Bad configuration option: usekeychain

To keep one config for all of them, tell ssh to ignore the option where it is unknown. This must come before the line that uses it:

IgnoreUnknown UseKeychain

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

To see which one you are running:

which ssh
ssh -V

Apple's build is at /usr/bin/ssh. The --apple- flags also exist only in Apple's /usr/bin/ssh-add.

Too many keys: IdentitiesOnly

By default, ssh offers every key in the agent, as well as the files you configured. With several keys this can end in Too many authentication failures, and it tells each server about keys it has no reason to see. Limit a host to one key:

Host server
  HostName 203.0.113.10
  User user
  IdentityFile ~/.ssh/id_ed25519_work
  IdentitiesOnly yes

IdentitiesOnly yes does not turn the agent off. If the agent holds the named key, ssh still uses it from there, so the passphrase is not asked for again. IdentityFile can even point to the .pub file when the private key is only in the agent.

Remove or limit a key

ssh-add -d ~/.ssh/id_ed25519                        # remove one key from the agent
ssh-add -D                                          # remove all keys from the agent
ssh-add --apple-use-keychain -d ~/.ssh/id_ed25519   # remove from the agent and the Keychain
ssh-add -t 3600 ~/.ssh/id_ed25519                   # keep the key loaded for one hour

Plain -d and -D only clear the agent. With UseKeychain yes the passphrase is still in the Keychain, and the key comes back on your next connection.

Anyone logged in as you on an unlocked Mac can use the keys in the agent, and so can any program you run. If that worries you, use AddKeysToAgent confirm so each use needs approval, but note that this needs a working SSH_ASKPASS program. Also think before using agent forwarding: see the risks of agent forwarding.

Questions

Why does my Mac keep asking for my SSH key passphrase?

Usually AddKeysToAgent yes or UseKeychain yes is missing from ~/.ssh/config. Add both, then run ssh-add --apple-use-keychain once with your key.

Does ssh-add -K still work on macOS?

Apple renamed it to --apple-use-keychain, and -A to --apple-load-keychain. In standard OpenSSH, -K means something else, related to hardware keys, so use the long names.

How do I see which keys are in ssh-agent?

Run ssh-add -l. It prints the fingerprint of each loaded key, or The agent has no identities. when it is empty.

Sources

More in Keys and login

From the blog

All guides