How the agent works
ssh web1 ──── "sign the server's challenge" ────→ ssh-agent ── key decrypted, in memory
↑ │
└──────────────────── signature ←─────────────────────┘
the server checks the signature with the public key from authorized_keys
The agent never hands out the private key — not to ssh, not to anyone. It only signs what it’s given. So
ssh, scp, git and an editor with remote development all use one key, and you type the passphrase once:
on ssh-add or on the first login with AddKeysToAgent yes (~/.ssh/config).
Where to keep the key
| Where | How the passphrase lives | When to use |
|---|---|---|
| the OS agent: the Windows service, Keychain on macOS, the session agent on Linux | Windows keeps an added key even across reboots — you type the passphrase once, ever. macOS and Linux — once per login | one computer, one or two keys |
| a password manager’s agent: KeePassXC, 1Password, Bitwarden | the key lives in the vault, and the agent opens with it | keys on several computers, and the vault syncs anyway |
a hardware key, ed25519-sk |
the private part never leaves the device; you log in with a touch | a laptop that might get stolen; access to important servers |
The rest of this page uses the OS agent: it’s everywhere and costs nothing.
Setup
Start the agent
Windows. The
ssh-agentservice is built in but disabled. In PowerShell as Administrator:Get-Service ssh-agent | Set-Service -StartupType Automatic Start-Service ssh-agent Get-Service ssh-agent # Status Name DisplayName # Running ssh-agent OpenSSH Authentication AgentmacOS. The system starts the agent itself.
Linux with a desktop. The session starts the agent: GNOME Keyring or the systemd
ssh-agentunit. Check thatecho $SSH_AUTH_SOCKisn’t empty.A server or a console without a desktop. In the current shell:
eval "$(ssh-agent -s)" # Agent pid 41873Add the key
ssh-add ~/.ssh/id_ed25519 # Enter passphrase for /home/me/.ssh/id_ed25519: # Identity added: /home/me/.ssh/id_ed25519 (laptop-2026)The parentheses hold the key’s comment from
ssh-keygen -C(SSH keys).On macOS, also store the key in Keychain so the passphrase isn’t asked after a reboot:
ssh-add --apple-use-keychain ~/.ssh/id_ed25519and add
UseKeychain yesunderHost *in~/.ssh/config.Point Git on Windows at the same ssh
Git for Windows ships its own
ssh.exe, which doesn’t see the Windows service:git pushkeeps asking for the passphrase. Point it at the system one:git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exeUse forward slashes: both git and the shells inside it understand them.
Restrict it on a shared computer
ssh-add -t 8h ~/.ssh/id_ed25519 # the key leaves the agent after 8 hours ssh-add -c ~/.ssh/id_ed25519 # every use needs confirmation in a window ssh-add -D # remove all keys from the agent-cneeds a confirmation program (ssh-askpass); without one, signing is silently refused.
Why not ForwardAgent
ssh -A or ForwardAgent yes forwards the agent to the server: a socket appears there that can sign logins
with your key — say, git pull from GitHub right on the server.
Your session isn’t the only thing that can sign through that socket. Root on the server can open your session’s
socket (its path is in $SSH_AUTH_SOCK) and, while you’re connected, log in with your key to any server or
repository the key opens. The key itself doesn’t leak — the ability to use it does. And a compromised server is
exactly that: a stranger with root.
| Task | Instead of agent forwarding |
|---|---|
| reach an internal server through a public one | ProxyJump (~/.ssh/config): the connection goes straight through, and the agent stays on your computer |
git pull on the server |
a deploy key on the server, read-only and for one repository (Server configs in git) |
| copy files between two servers | scp -3 web1:/a web2:/b routes through your computer; or a backup key with restrict (SSH keys) |
If you do need forwarding, use it for one command and with confirmation: ssh-add -c and ssh -A web1.
And close it on your own servers: AllowAgentForwarding no (sshd_config).
If it doesn’t work
Could not open a connection to your authentication agent.
- Cause
- The agent isn’t running in this session, or
SSH_AUTH_SOCKpoints to a socket that’s gone. - Fix
- Linux:
eval "$(ssh-agent -s)"andssh-add. Windows: thessh-agentservice — step 1.
On Windows: Error connecting to agent: No such file or directory
- Cause
- The
ssh-agentservice is stopped; Windows ships it disabled (Disabled). - Fix
- Set it to start automatically and start it — step 1, in PowerShell as Administrator.
The key is in the agent, but git push still asks for the passphrase
- Cause
- Git for Windows runs its own
ssh.exe, which doesn’t see the Windows service. - Fix
git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exe.
sign_and_send_pubkey: signing failed for ED25519 … agent refused operation
- Cause
- The key in the agent is locked or has expired (
ssh-add -t), or it was added with confirmation (-c) and there’s no window to confirm in. - Fix
ssh-add -lshows what’s in the agent; add the key again withssh-add ~/.ssh/id_ed25519.
Many keys in the agent, and the server drops the connection: Too many authentication failures
- Cause
- The agent offers every key in turn.
- Fix
IdentitiesOnly yesandIdentityFilefor the host (~/.ssh/config).
How to check
What’s in the agent:
ssh-add -l
# 256 SHA256:u7WTRQvHCGalFd0cVdGQ7Wm7cULmdHtHUpyj6Q0uXcA laptop-2026 (ED25519)
If it’s empty: The agent has no identities.
The login goes through the agent, not the file: in the debug output the key is marked agent.
ssh -v web1 true 2>&1 | grep 'Offering'
# debug1: Offering public key: /home/me/.ssh/id_ed25519 ED25519 SHA256:u7WT… explicit agent
The agent isn’t forwarded to the server:
ssh web1 'echo ${SSH_AUTH_SOCK:-no agent}'
# no agent