SSH-agent Not Running on macOS: Quick Fix

What the "ssh-agent not running" Error Means

The error ssh-agent not running (or Could not open a connection to your authentication agent) occurs when commands that work with SSH keys (e.g., ssh-add, git over SSH) cannot find a running ssh-agent process and its associated Unix socket.

Symptoms:

• Running ssh-add -l or ssh-add ~/.ssh/your_key fails with the specified error.
• git clone, git push, or git pull operations over SSH prompt for a password and may fail.
• Connecting to a remote server via ssh user@host might require a password instead of using the key.

This means your system doesn't have a working "storage" for decrypted private SSH keys in memory.

Common Causes

1. The agent is not set to auto-launch. In modern versions of macOS (starting with Catalina), zsh is the default shell, and the SSH agent might not be added to autostart when a new user is created or after resetting settings.
2. The SSH_AUTH_SOCK environment variable is not set. Even if the agent is running, the terminal needs to know which socket to connect to. This variable can be lost when restarting the terminal or if the shell profile isn't configured.
3. Issues with launchd management. The SSH agent on macOS is managed by the system launchd manager. If the configuration in ~/Library/LaunchAgents/ is corrupted or missing, the agent won't start.
4. Conflict with another agent. Another SSH agent (e.g., from a key manager) might be running on the system, causing a conflict or socket hijacking.

Solution 1: Manually Start the Agent (Quick Fix)

This solves the problem for the current terminal session.

1. Start the agent and get the environment variables:

   eval "$(ssh-agent -s)"
   

   The ssh-agent -s command outputs commands to set the SSH_AGENT_PID (process ID) and SSH_AUTH_SOCK (socket path) variables. eval executes them in the current shell.

macOS terminal showing the output of the ssh-agent command and setting environment variables

2. Add your SSH key to the agent:

   ssh-add ~/.ssh/id_rsa
   

   If you have a different key type (e.g., Ed25519) or a different filename, specify the correct path. If the key is password-protected, the system will prompt for it once.

After this, ssh-add -l and git operations should work.

Solution 2: Configure Autostart via Shell Profile (Permanent Solution)

To have the agent start automatically every time you open a terminal, you need to add initialization to your shell's configuration file.

.zshrc configuration file with ssh-agent autostart settings

1. Determine which shell you are using:

   echo $SHELL
   

   
   The output will be /bin/zsh (default since Catalina) or /bin/bash.
2. Open the corresponding profile file in a text editor:
   • For zsh: nano ~/.zshrc
   • For bash: nano ~/.bash_profile (or ~/.bashrc)
3. Add the following lines to the end of the file:

   # Start ssh-agent if it's not already running
   if [ -z "$SSH_AUTH_SOCK" ] ; then
     eval "$(ssh-agent -s)"
   fi
   

   
   This block checks if the SSH_AUTH_SOCK variable already exists. If not, it starts the agent and exports the variables.
4. Save the file (Ctrl+O, Enter, Ctrl+X in nano) and apply the changes:

   source ~/.zshrc  # or source ~/.bash_profile
   

   
   Or simply open a new terminal window.
5. Add the key once (if you haven't already): ssh-add ~/.ssh/id_rsa.

Solution 3: Use the macOS Keychain Manager

macOS has a built-in system keychain that can store SSH keys. This is the most integrated method.

Command to add an SSH key to macOS Keychain using ssh-add -K

1. Add the key to the keychain on first use:

   ssh-add -K ~/.ssh/id_rsa
   

   
   The -K (uppercase K) flag adds the key to the macOS Keychain. After this, the system will automatically start the agent and load the key from the keychain at login. For macOS 12.0 (Monterey) and newer, you can use ssh-add --apple-use-keychain ~/.ssh/id_rsa.
2. Ensure your ~/.ssh/config (if it exists) doesn't override this. Recommended config for keychain integration:

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

Solution 4: Check and Fix Socket Permissions

Sometimes the issue is incorrect permissions on the /tmp directory or the agent's socket.

1. Check if the socket exists:

   ls -l $SSH_AUTH_SOCK
   

   
   If the variable is empty or the path doesn't exist, the agent didn't create the socket.
2. Restart the agent manually (Solution 1) and check again. If the problem persists, check permissions on temporary files:

   sudo chmod 1777 /tmp
   

   
   These are standard permissions for /tmp (sticky bit). Be cautious when modifying system directories.

Prevention

• Always configure autostart via your shell profile (Solution 2) or use the keychain (Solution 3).
• After a macOS update or a shell change (e.g., from bash to zsh), verify that your profile file (.zshrc) contains the ssh-agent settings.
• Do not manually delete socket files in /tmp/ (e.g., /tmp/ssh-*/agent.*). This can leave "stale" references. It's better to restart the agent.
• Regularly update your system: softwareupdate --install --all to receive fixes for security components and launchd.