Back to Commands

ssh-agent

networkingLinux/Unix/Windows
The ssh-agent command is one of the most frequently used commands in Linux/Unix-like operating systems. ssh-agent The ssh-agent command starts an authentication agent that can store private keys for SSH authentication. It allows users to authenticate to SSH servers without having to constantly re-enter their private key passphrase, providing both convenience and security by keeping keys encrypted on disk but available for use during a session.
See ExamplesView Syntax

Quick Reference

Command Name:

ssh-agent

Category:

networking

Platform:

Linux/Unix/Windows

Basic Usage:

ssh-agent [options] [arguments]

Common Use Cases

  • 1

    SSH key management

    Manage SSH keys in 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-agent [options] [command [args ...]]

Options

Option Description
-a socket Bind the agent to a specific UNIX-domain socket
-c Generate C-shell commands on stdout
-d Debug mode
-k Kill the current agent (given by the SSH_AGENT_PID environment variable)
-s Generate Bourne shell commands on stdout (default)
-t seconds Set a default maximum lifetime for identities added to the agent

Examples

How to Use These Examples

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

Basic Usage:

ssh-agent

Start the SSH agent and output shell commands for setting the required environment variables.

eval $(ssh-agent)

Start the SSH agent and set the environment variables in the current shell.

ssh-agent bash

Start the SSH agent and spawn a new bash shell with the correct environment variables.

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

Start the SSH agent, set environment variables, and load the default SSH keys.

Managing the Agent:

ssh-agent -k

Kill the running SSH agent process.

ssh-agent -t 3600

Start an agent that will automatically expire after 1 hour (3600 seconds).

ssh-agent -s

Generate Bourne shell commands to set the environment variables.

ssh-agent -c

Generate C-shell commands to set the environment variables.

Advanced Usage:

ssh-agent bash -c 'ssh-add ~/.ssh/id_rsa && ssh user@hostname'

Start the agent, add a key, and run an SSH command, all in one line.

ssh-agent -a /tmp/ssh-agent.socket bash

Specify a custom socket path for the SSH agent.

SSH_AUTH_SOCK=/tmp/ssh-agent.socket ssh-add -l

Connect to a specific SSH agent using a custom socket path.

ssh-agent -d

Debug mode - sends verbose output to stderr.

echo $SSH_AGENT_PID

Check if an SSH agent is running in the current session by looking at the PID environment variable.

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 creates a Unix socket and listens for connections from SSH clients
  • Environment variables (SSH_AUTH_SOCK and SSH_AGENT_PID) point to the socket and agent process
  • Private keys are added to the agent with the ssh-add command
  • When an SSH client needs to authenticate, it connects to the agent's socket
  • The agent performs the cryptographic operations without revealing the private key
  • Keys remain securely encrypted on disk, but the agent keeps decrypted copies in memory

Security Considerations:

  • The agent holds decrypted private keys in memory, so it should only be used on trusted machines
  • Always kill your SSH agent when finished with sensitive work on shared systems
  • Consider using key timeouts (-t option) for additional security
  • The agent socket grants access to your keys - protect its permissions (typically 600)
  • Be cautious with agent forwarding (ssh -A), as it can expose your agent to remote systems
  • On multi-user systems, ensure your agent socket isn't accessible to others

Platform-Specific Notes:

  • macOS: SSH agent integration is built into Keychain and starts automatically
  • Windows (with OpenSSH): Can be run as a service with "ssh-agent -A" as administrator
  • Linux with systemd: Can be configured to start on login with systemd user services
  • GNOME/KDE: Desktop environments often start ssh-agent automatically on login
  • WSL (Windows Subsystem for Linux): May require extra configuration to use the Windows OpenSSH agent

Automatic Startup Configuration:

  • Bash: Add "eval $(ssh-agent)" to ~/.bashrc or ~/.bash_profile
  • Zsh: Add "eval $(ssh-agent)" to ~/.zshrc
  • Fish: Use "eval (ssh-agent -c)" in ~/.config/fish/config.fish
  • Consider adding a conditional check to avoid starting multiple agents:
  • if [ -z "$SSH_AUTH_SOCK" ]; then eval $(ssh-agent -s); fi
  • Add automatic key loading with "ssh-add" after starting the agent

Troubleshooting:

  • "Could not open a connection to your authentication agent": SSH_AUTH_SOCK isn't set or agent isn't running
  • "Agent admitted failure to sign": The required key isn't loaded in the agent
  • "Error connecting to agent: No such file or directory": The socket file doesn't exist or has incorrect permissions
  • "Error connecting to agent: Permission denied": The socket file has restrictive permissions
  • Check if the agent is running with "ps -ef | grep ssh-agent" or "echo $SSH_AGENT_PID"
  • Verify the socket exists with "ls -la $SSH_AUTH_SOCK"
  • List loaded keys with "ssh-add -l" to verify your keys are available

Common Patterns:

  • Start a new agent for each login session
  • Use a single, persistent agent across all terminals
  • Create a temporary agent for a specific task and then kill it
  • Use agent forwarding for multi-hop SSH connections (with security considerations)
  • Configure automatic startup in shell profile scripts

Related Commands:

  • ssh-add - Add keys to the running SSH agent
  • ssh - Secure Shell client that uses the agent for authentication
  • 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 -a option to specify the agent socket

2

Use the -c option to specify the command to run

3

Use the -d option to specify the directory for the agent socket

4

Use the -s option to specify the shell to use

5

Use the -l option to list identities

Common Use Cases

SSH key management

Manage SSH keys in 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-agent or serve similar purposes:

Explore All Commands

Use Cases

1

SSH key management

Manage SSH keys in 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-agent command works in different scenarios.

See ExamplesTry Lab Exercises
$ ssh-agent
View All Commands