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

    Key management

    Start an authentication agent to securely store private keys in memory

  • 2

    Passwordless login

    Enable SSH connections without having to enter your passphrase each time

  • 3

    Session-based security

    Keep keys available for the duration of a login session but encrypted on disk

  • 4

    Shell integration

    Integrate with different shell environments using the appropriate output format

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

Proper shell integration: eval $(ssh-agent) to set environment variables in your current shell

2

One-liner setup: eval $(ssh-agent) && ssh-add to start agent and add keys in one step

3

Prevent multiple agents: if [ -z "$SSH_AUTH_SOCK" ]; then eval $(ssh-agent); fi to only start if not running

4

Auto-kill on logout: ssh-agent bash -c "trap 'ssh-agent -k' EXIT; bash" creates an agent that dies with the shell

5

Shell-specific output: ssh-agent -c for C shell, ssh-agent -s for Bourne shell (default)

6

Custom socket location: ssh-agent -a /path/to/socket for specifying where the socket file lives

7

Timeouts for added keys: ssh-agent -t 3600 sets a 1-hour default timeout for all added keys

8

Kill existing agent: ssh-agent -k kills the agent specified by current environment variables

9

Debug mode: ssh-agent -d for verbose output to troubleshoot connection issues

Common Use Cases

Key management

Start an authentication agent to securely store private keys in memory

Passwordless login

Enable SSH connections without having to enter your passphrase each time

Session-based security

Keep keys available for the duration of a login session but encrypted on disk

Shell integration

Integrate with different shell environments using the appropriate output format

Centralized authentication

Provide a central point of authentication for multiple SSH connections

Related Commands

ssh-add

ssh-add

View command

ssh

ssh

View command

ssh-keygen

ssh-keygen

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

See ExamplesTry Lab Exercises
$ ssh-agent
View All Commands