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

    SSH key management

    Add SSH keys to the SSH agent for password-less authentication

  • 2

    Security

    Ensure secure communication between systems

  • 3

    Scripting

    Use in shell scripts to automate SSH key management

  • 4

    Remote administration

    Administer remote systems securely

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

Use the -l option to list identities

2

Use the -d option to delete identities

3

Use the -t option to specify the lifetime of the key

4

Use the -s option to specify the key type

5

Use the -c option to specify the key comment

Common Use Cases

SSH key management

Add SSH keys to the SSH agent for password-less authentication

Security

Ensure secure communication between systems

Scripting

Use in shell scripts to automate SSH key management

Remote administration

Administer remote systems securely

Data transfer

Transfer files between systems securely and efficiently

Related Commands

These commands are frequently used alongside ssh-add or serve similar purposes:

Explore All Commands

Use Cases

1

SSH key management

Add SSH keys to the SSH agent for password-less authentication

2

Security

Ensure secure communication between systems

3

Scripting

Use in shell scripts to automate SSH key management

4

Remote administration

Administer remote systems securely

5

Data transfer

Transfer files between systems securely and efficiently

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