Skip to content

ssh-agent

SSH agent is a program that helps manage SSH private keys and automatically uses them when attempting to connect to a remote server. To add a key to the agent, run the following command:

eval "$(ssh-agent -s)"

This command will start the SSH agent and set environment variables for the current shell session. If the command executes successfully, you will see the following:

macOS

Depending on the environment you are using, you may need the following commands:

  • sudo -s -H for root access before starting the SSH agent;
  • exec ssh-agent bash or exec ssh-agent zsh to start the SSH agent.

If you are using macOS Sierra 10.12.2 or later, to automatically load keys into the SSH agent and store passphrases in the keychain, you will need to modify the ~/.ssh/config file:

  1. First, check if the file exists:

open ~/.ssh/config

Instead of open, you can use other commands, for example, ls or code ~/.ssh/config.

If the file exists, it will open in a text editor, for example:

  1. If the file does not exist, you will get approximately the following message:

The file /Users/YOU/.ssh/config does not exist.

You can create it with the following command:

touch ~/.ssh/config

You can create this file in a different way; the important thing is that it is in the correct location.

Next, open the file and paste the following text into it:

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

If no passphrase was added to the key in the second step, you do not need to add the UseKeychain line to the file.

  1. Save the file.

If after saving the file you see the error Bad configuration option: usekeychain, add the line `Host*.github.com` to the file.

Add your SSH private key to the agent and save your passphrase in the keychain. If the key was created with a different name, or if you are adding an existing key with a different name, replace id_ed25519 in the command with the name of your private key file. To do this, run the following command:

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

Note: when you add an SSH key to the agent, the --apple-use-keychain option stores the passphrase in the keychain. If no passphrase was added to the key, run the command without the --apple-use-keychain option:

ssh-add ~/.ssh/id_ed25519

Here is an example of execution:

The --apple-use-keychain option is available in the standard Apple version of ssh-add. In macOS versions prior to Monterey (12.0), the --apple-use-keychain and --apple-load-keychain options use the -K and -A syntax respectively.

If you do not have the standard Apple version of ssh-add installed, you may receive the error Error: ssh-add: illegal option -- K.

If the passphrase prompt keeps appearing, you may need to add the command to the ~/.zshrc file (or ~/.bashrc for Bash).

Step 4. Adding the key to a GitHub account

Next, you need to copy the key to the clipboard. If you are using Windows, run the following command:

clip < ~/.ssh/id_ed25519.pub

For macOS, you can use this command:

pbcopy < ~/.ssh/id_ed25519.pub

The terminal will not "respond" with anything, but the key should be in the clipboard when using the "Paste" option:

Now open your GitHub account and click on your avatar in the upper right corner. Select the Settings tab:

On the left, in the Access section, select SSH and GPG keys:

Next to SSH keys, click the New SSH key or Add SSH key button:

Then perform the following actions:

  1. In the Title field, add a descriptive label for the new key. For example, "Personal laptop".
  2. Choose the key type: Authentication Key or Signing Key. You can find additional information about commit signing in the documentation About commit signature verification. If you are unsure which to choose, leave the default value — Authentication Key.
  3. In the Key field, paste the copied key.
  4. Click the [Add SSH key] button.

You may need to enter your GitHub account password to confirm this operation — go ahead and do so. For additional information, see the Sudo mode section.

Step 5. Testing

Return to the terminal and run the following command:

ssh -T git@github.com

If you receive a similar message, everything is fine:

If you see the following messages:

The authenticity of host 'github.com (IP ADDRESS)' can't be established.

ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.

Are you sure you want to continue connecting (yes/no)?

...type yes in the terminal and press ENTER.

Congratulations! Your key has been added!