macOS Sonoma changes how the SSH agent manages keys, often causing repeated passphrase prompts because the old caching mechanism was removed. To restore seamless authentication, you must configure your SSH client to use the system keychain or update your local configuration files. This guide explains the correct diagnostic steps and configuration updates needed to resolve this issue without relying on deprecated commands.
Understanding the Change in macOS Sonoma
Prior to macOS Ventura, users could rely on the
ssh-add -K command to cache their private key passphrases in the macOS Keychain. This command has been removed from modern versions of OpenSSH bundled with Apple Silicon and Intel Macs running recent operating systems. When you upgrade to Sonoma, any existing scripts or configurations that depended on this flag will fail silently or produce errors, leading to the persistent prompt for your passphrase every time you initiate a connection.
The underlying cause is not a bug in your SSH keys themselves, but rather a shift in how the SSH agent interacts with the operating system’s security infrastructure. The SSH agent no longer automatically stores credentials in the Keychain by default. Instead, it expects explicit configuration via the
.ssh/config file or relies on manual additions to the agent using the
-A flag for forwarding, which does not solve the local caching problem. If you are seeing prompts even when using a Git server, it confirms that the issue is local to your machine’s SSH client configuration rather than a network or remote server authentication failure.
Verifying Your Current Configuration
Before making changes, it is helpful to verify that your SSH keys are correctly recognized by the system. You can check if your private key is loaded into the agent by running the following command in Terminal:
ssh-add -l
If this command returns "The agent has no identities," then your key is not being loaded at all, which might indicate a different issue such as incorrect file permissions. However, if you see your key fingerprint listed but still get prompted for a password, the agent is aware of the key but lacks the cached passphrase. In this scenario, you need to adjust how the SSH client requests the passphrase from the Keychain.
Configuring SSH for Keychain Integration
The most reliable solution for macOS Sonoma involves editing the user-specific SSH configuration file. This method tells the SSH client exactly where to look for the passphrase when connecting to specific hosts or all hosts by default.
First, locate or create the configuration file in your home directory. You can do this by opening Terminal and entering the following command to open the file in a text editor like Nano:
nano ~/.ssh/config
If the file does not exist, Nano will create it upon saving. Inside this file, you need to add a global configuration block that instructs SSH to use the macOS Keychain for storing passphrases. Add the following lines to the top of the file:
Host *
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_rsa
Let us break down what these directives do. The
Host * line applies these settings to all connections. The
AddKeysToAgent yes directive ensures that whenever you enter your passphrase, it is added to the running SSH agent session. The critical part for Sonoma compatibility is
UseKeychain yes, which explicitly tells the SSH client to store the passphrase in the macOS Keychain after you type it once. Finally,
IdentityFile should point to your actual private key location; if you use a different key name, such as
id_ed25519, you must update this path accordingly.
After adding these lines, save the file and exit the editor. If you are using Nano, press
Control+O to write out, then
Control+X to exit.
Applying the Changes
Once the configuration file is updated, you need to ensure your current SSH agent session picks up these new rules. It is best practice to remove any existing keys from the agent before re-adding them to avoid conflicts. Run the following command to clear the current agent:
ssh-add -D
Next, add your private key back into the agent. Because your configuration file now includes
UseKeychain yes, you will be prompted for your passphrase one last time. Upon successful entry, the passphrase will be stored securely in the Keychain, and future connections will not require you to type it again.
ssh-add ~/.ssh/id_rsa
You can verify that the key is now associated with the Keychain by checking the agent list again. You should see your key fingerprint listed without any errors. Test the connection by attempting to SSH into a known host or cloning a Git repository. The process should now proceed without prompting for a password.
For more context on terminal issues that may arise during setup, you might find it useful to review
Fixing zsh: command not found: ssh -Y on Mac Terminal, which addresses common shell configuration hurdles. Additionally, understanding how system changes affect your keys can prevent unexpected behavior, as discussed in
Does Changing a Mac's Name Affect Its SSH Key?.
Troubleshooting Common Issues
Even with the correct configuration, some users may encounter residual problems. If you continue to receive passphrase prompts, check the file permissions of your SSH directory and keys. The private key file must have restrictive permissions, typically set to 600. You can enforce this by running:
chmod 600 ~/.ssh/id_rsa
Additionally, ensure that there are no conflicting entries in your
.bash_profile or
.zshrc files that might be overriding the
.ssh/config settings. Sometimes, older aliases or export statements related to SSH can interfere with the new Keychain integration. If you suspect a conflict, try commenting out any SSH-related exports in your shell profile and restart your Terminal session.
Another potential culprit is the state of the SSH agent itself. On rare occasions, the agent process may become corrupted or stuck. You can force a restart of the agent by killing the current process and letting the system spawn a new one. Run
killall ssh-agent and then attempt an SSH connection again; the system will automatically start a fresh agent instance.
Conclusion
The transition to macOS Sonoma requires a shift away from deprecated SSH commands toward explicit configuration file settings. By updating your
.ssh/config file to include
UseKeychain yes, you align your client with the modern security model of macOS. This approach provides a permanent fix for the repeated passphrase prompts, ensuring a smoother development workflow. Remember to keep your keys secure and regularly update your configuration if you migrate to different hardware or operating system versions.
Frequently Asked Questions
Why did my SSH passphrase stop working after the update?
Apple removed the
ssh-add -K command in recent macOS versions, which previously handled automatic passphrase caching. Without updating your configuration to use the new
UseKeychain directive, the SSH agent no longer retains your credentials between sessions.
Can I use SSH keys without a passphrase on macOS?
Yes, you can generate keys without a passphrase by omitting the password step during creation, but this is generally discouraged for security reasons. Storing the passphrase in the Keychain via the configuration method described above offers a better balance of convenience and security.
What should I do if ssh-add -l shows no identities?
This indicates that no keys are currently loaded into the agent. You should run
ssh-add followed by the path to your private key (e.g.,
~/.ssh/id_rsa) to load it. Ensure your
.ssh/config file is correctly formatted to allow the agent to access the Keychain.
Does changing my Mac's hostname affect SSH keys?
No, changing the computer name in System Settings does not invalidate your SSH keys. However, it is good practice to verify your
.ssh/config settings after major system changes to ensure no paths or environment variables have been inadvertently altered.
How do I reset my SSH agent if it becomes unresponsive?
You can reset the agent by terminating all active agent processes using the
killall ssh-agent command in Terminal. After killing the process, your next SSH command will automatically start a new, clean agent instance.