Back to Commands

ssh-add

networkingLinux/Unix/Windows
The ssh-add command is one of the most frequently used commands in Linux/Unix-like operating systems. ssh-add The ssh-add command adds SSH private keys to the SSH authentication agent (ssh-agent). It allows you to load your keys into memory so you can use SSH without entering your passphrase each time, while keeping your keys securely encrypted on disk.
See ExamplesView Syntax

Quick Reference

Command Name:

ssh-add

Category:

networking

Platform:

Linux/Unix/Windows

Basic Usage:

ssh-add [options] [arguments]

Common Use Cases

  • 1

    Key caching

    Load private keys into the SSH agent to avoid typing passphrases repeatedly

  • 2

    Identity management

    Add, remove, and list keys managed by the SSH authentication agent

  • 3

    Agent security

    Lock and unlock the SSH agent or add keys with time limits for better security

  • 4

    Hardware key integration

    Work with FIDO/U2F keys and smartcards for enhanced security

Syntax

ssh-add [options] [file ...]

Options

Option Description
-c Confirm each use of the key (requires user confirmation)
-D Delete all identities from the agent
-d Remove the specified key from the agent
-e pkcs11.so Remove keys provided by the PKCS#11 shared library
-k Load resident keys from a FIDO authenticator
-K Load resident keys from a FIDO authenticator and keys listed in ~/.ssh/known_hosts
-l List fingerprints of all identities currently represented by the agent
-L List public key parameters of all identities currently represented by the agent
-s pkcs11.so Add keys provided by the PKCS#11 shared library
-t seconds Set a maximum lifetime when adding identities to an agent
-v Verbose mode, useful for debugging
-X Unlock the agent
-x Lock the agent with a password

Examples

How to Use These Examples

The examples below show common ways to use the ssh-add command. Try them in your terminal to see the results. You can copy any example by clicking on the code block.

#

Basic Usage:

ssh-add

Add default SSH keys (~/.ssh/id_rsa, ~/.ssh/id_dsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ed25519) to the agent.

ssh-add ~/.ssh/custom_key

Add a specific private key to the SSH agent.

ssh-add -l

List fingerprints of all identities currently represented by the agent.

ssh-add -L

List public key parameters of all identities currently represented by the agent.

Key Management:

ssh-add -d ~/.ssh/id_rsa

Remove a specific key from the agent.

ssh-add -D

Delete all identities from the agent.

ssh-add -x

Lock the agent with a password.

ssh-add -X

Unlock the agent.

Advanced Usage:

ssh-add -t 3600 ~/.ssh/id_rsa

Add a key with a time limit of 1 hour (3600 seconds).

ssh-add -c ~/.ssh/id_rsa

Add a key with confirmation required for each use.

ssh-add -k

Load resident keys from a FIDO authenticator.

ssh-add -e pkcs11.so

Remove keys provided by the PKCS#11 shared library.

eval $(ssh-agent) && ssh-add

Start the SSH agent and add your keys in one command.

Try It Yourself

Practice makes perfect! The best way to learn is by trying these examples on your own system with real files.

Understanding Syntax

Pay attention to the syntax coloring: commands, options, and file paths are highlighted differently.

Notes

How SSH Agent Works:

  • The SSH agent (ssh-agent) holds private keys in memory, so you don't need to store keys unencrypted on disk
  • The agent responds to signature requests from SSH clients, providing authentication without requiring your passphrase each time
  • The agent uses socket files for communication, with the socket path stored in the SSH_AUTH_SOCK environment variable
  • When you add a key with ssh-add, the agent decrypts it using your passphrase and keeps the decrypted key in memory
  • The agent never reveals the private key to clients, only performing signature operations on their behalf

Security Considerations:

  • Only add keys to the agent on trusted systems
  • Use time limits (-t option) when adding keys in potentially untrusted environments
  • Consider using the confirmation option (-c) for particularly sensitive keys
  • On shared systems, use ssh-add -D to clear all keys when you're done
  • The agent is typically tied to your login session and will exit when you log out
  • Agent forwarding (ssh -A) can pose security risks in untrusted environments
  • Use locking (-x/-X) when leaving your computer temporarily

Agent Forwarding:

  • When enabled with ssh -A, your local agent can be accessed remotely to authenticate to other servers
  • This allows you to hop between servers without copying your private keys to intermediate systems
  • Agent forwarding should be used carefully, as compromised servers could use your forwarded agent
  • Consider using ProxyJump (ssh -J) as a more secure alternative in many cases
  • Agent forwarding can be configured per-host in ~/.ssh/config with "ForwardAgent yes"

Working with Hardware Keys:

  • Modern SSH supports FIDO/U2F hardware security keys
  • Use ssh-add -k to load resident keys from FIDO authenticators
  • Hardware keys provide additional protection as the private key material never leaves the device
  • PKCS#11 libraries (-s/-e options) allow integration with smart cards and hardware security modules

Common Issues:

  • "Could not open a connection to your authentication agent" - Usually means ssh-agent isn't running or SSH_AUTH_SOCK isn't set properly
  • "Agent refused operation" - Can occur if the agent is locked or there are permission issues with the socket
  • "Bad passphrase" - Entered incorrect passphrase for the private key
  • "Error connecting to agent: Connection refused" - The agent process may have died or the socket location is incorrect
  • On some systems, ssh-agent needs to be started manually (eval $(ssh-agent))

Platform-Specific Notes:

  • macOS: The SSH agent is integrated with Keychain and runs automatically
  • Windows (with OpenSSH): The agent can be set as a service via "ssh-agent -A" with administrator privileges
  • Linux desktops: Most desktop environments start ssh-agent automatically with your login session
  • WSL (Windows Subsystem for Linux): May require extra configuration to connect to the Windows OpenSSH agent

Related Commands:

  • ssh-agent - Authentication agent that stores unencrypted keys in memory
  • ssh - Secure Shell client for remote login
  • ssh-keygen - Generate and manage SSH keys
  • ssh-copy-id - Install your public key in a remote machine's authorized_keys
  • scp - Secure Copy, transfers files securely using SSH protocol
  • sftp - Secure FTP, provides FTP-like interface over SSH

Tips & Tricks

1

Start the SSH agent: eval $(ssh-agent) before using ssh-add if it's not running

2

List loaded keys: ssh-add -l shows fingerprints of currently loaded keys

3

Set time limits: ssh-add -t 3600 ~/.ssh/id_rsa adds a key for just one hour

4

Verify keys are loaded: ssh-add -L shows the full public key of all loaded identities

5

Clear all keys: ssh-add -D removes all identities from the agent

6

Lock your agent: ssh-add -x before leaving your computer temporarily

7

Add confirmation requirement: ssh-add -c ~/.ssh/id_rsa for extra security on sensitive keys

8

Auto-start the agent: Add eval $(ssh-agent) to your shell startup file (.bashrc or .zshrc)

9

Debugging connection issues: ssh-add -v for verbose output when troubleshooting

Common Use Cases

Key caching

Load private keys into the SSH agent to avoid typing passphrases repeatedly

Identity management

Add, remove, and list keys managed by the SSH authentication agent

Agent security

Lock and unlock the SSH agent or add keys with time limits for better security

Hardware key integration

Work with FIDO/U2F keys and smartcards for enhanced security

Multi-server authentication

Enable seamless authentication across multiple SSH sessions

Related Commands

ssh

ssh

View command

ssh-keygen

ssh-keygen

View command

ssh-agent

ssh-agent

View command

ssh-copy-id

ssh-copy-id

View command

scp

scp

View command

sftp

sftp

View command

ssh-import-id

ssh-import-id

View command

Learn By Doing

The best way to learn Linux commands is by practicing. Try out these examples in your terminal to build muscle memory and understand how the ssh-add command works in different scenarios.

See ExamplesTry Lab Exercises
$ ssh-add
View All Commands