Using the SSH Agent and Keychain on macOS

If SSH on your Mac keeps asking for your key’s passphrase, the fix usually isn’t to start another agent. macOS normally provides an SSH agent for your login session. First check whether your terminal can reach it; then add your key and, if you use Apple’s OpenSSH, save its passphrase in Keychain.

Check the agent you already have

In Terminal, run:

echo "$SSH_AUTH_SOCK"
ssh-add -l

SSH_AUTH_SOCK should contain a path to the agent socket. The output from ssh-add -l helps distinguish two common situations:

• A fingerprint is listed: the agent is reachable and has a key loaded.
• “The agent has no identities.” The agent answered, but no keys are loaded.
• The command can’t connect: this shell may not have access to an agent socket, or it may be configured to use a different agent.

That last case doesn’t automatically mean you should launch a new agent. Adding eval "$(ssh-agent -s)" to your shell startup file can create an extra agent rather than reconnecting your terminal to the session agent. For the socket’s role and common causes of missing or stale values, see this explanation of SSH_AUTH_SOCK and agent connections.

If you’re in a standalone shell that genuinely has no agent, you can start one for that shell:

eval "$(ssh-agent -s)"

Keep that shell open and use it for SSH commands, since the agent details are in its environment.

Add a key and save its passphrase

First check what keys you have:

ls -la ~/.ssh

A private key is usually the file without a .pub suffix. For example, id_ed25519 is the private key and id_ed25519.pub is its public counterpart. Use the actual private-key path if yours has a different name.

With Apple’s OpenSSH, add an Ed25519 key and ask macOS to store its passphrase in Keychain:

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

Enter the passphrase when prompted. The key is added to the agent, and macOS Keychain stores the passphrase. The private key stays in ~/.ssh; this does not upload it or replace it with a Keychain key file.

To see whether the identity is loaded, run:

ssh-add -l

To print the public-key lines for loaded identities, use:

ssh-add -L

These commands report on the agent your current shell can access. Another terminal or application may use a different SSH client or agent, so it may not show the same identities.

Make SSH use the key automatically

You can put the relevant settings in ~/.ssh/config. For a default key, the configuration can look like this:

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

AddKeysToAgent yes tells SSH to add the key when it is used. UseKeychain yes enables Keychain integration in Apple’s OpenSSH, and IdentityFile points SSH to the key. These settings are related but do different jobs: loading a key into an agent and retrieving its saved passphrase are not the same thing.

If you use different keys for different servers, scope the settings to the relevant host instead of applying one identity everywhere:

Host code.example.com
    AddKeysToAgent yes
    UseKeychain yes
    IdentityFile ~/.ssh/id_ed25519_work

Replace the host pattern and key path with your own. Choosing the right key per host can also prevent SSH from offering an unrelated identity; see how to select a private key with IdentityFile.

When the Keychain option is rejected

Apple’s --apple-use-keychain option and UseKeychain setting are not supported by every OpenSSH build. Check which tools your shell will run:

which ssh
which ssh-add
/usr/bin/ssh -V

If ssh-add resolves to a Homebrew or other third-party installation, try Apple’s executable explicitly:

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

If SSH reports Bad configuration option: UseKeychain, the client reading your config may not support Apple’s setting. Using Apple’s ssh-add alone won’t change which client reads ~/.ssh/config; check both executables and make sure the client and agent you intend to use are the ones active in that terminal. Older macOS releases used -K for Keychain integration; current Apple OpenSSH uses --apple-use-keychain.

If the passphrase prompt keeps returning, verify that IdentityFile points to the same key you added, and check ssh-add -l in the terminal where the problem occurs. Don’t assume that every app shares the same agent or SSH installation.

Keep agent forwarding separate

Adding a key to your Mac’s agent is for SSH connections initiated from your Mac. Agent forwarding is different: it allows a remote session to request authentication through your local agent so it can connect onward to another host.

Forwarding does not copy your private-key file to the remote server, but a process on that server may be able to request authentication through the forwarded connection while the session is active. It is not needed for ordinary SSH connections. If you need it, enable it only for a host you trust:

Host trusted-jump
    ForwardAgent yes

For everyday use, the practical sequence is simple: check the existing agent, add the correct key with Apple’s Keychain option, configure the matching identity, and verify it with ssh-add -l. If one terminal still behaves differently, check its agent socket and SSH executables before starting another agent.

I originally published a more detailed version of this guide on the SSHFlow blog.

I'm also building SSHFlow — an SSH client where every server gets its own workspace for terminals, SFTP, code, and databases.