Search for a command to run...
Or: "The SSH Agent Guide Your Sysadmin Forgot to Write"
No comments yet. Be the first to comment.
SSH keys are better than passwords, but typing passphrases 50 times a day isn't fun, either. That's what ssh-agent solves - you unlock your key once, and the agent handles authentication from there.
This guide covers SSH agent setup on all three major platforms in 2026, including some platform-specific tricks that most tutorials skip.
⚠️ Multi-Account Users: If you use multiple GitHub/GitLab accounts from the same desktop, don't follow this guide yet - there's a footgun. I'll get a new post up on that asap.
Before configuring agents, you need a key. This works the same everywhere:
ssh-keygen -t ed25519 -C "your-hostname-2026-02-17"
Press Enter to accept the default location (~/.ssh/id_ed25519).
Passphrase decision:
ℹ️Why ed25519? Modern algorithm, fast, small keys (68 bytes public key vs 544 for RSA-4096). Supported on OpenSSH 6.5+ (2014), so works everywhere that matters.
ℹ️
"your-hostname-2026-02-17": Most guides will have-C "your-email@example.com"but that stopped making sense when we got off VT100 terminals. It's just a comment. It helps you recognize where the key came from later when you see it in someauthorized_keysfile.
Windows 10/11 ships with an SSH agent, but it's disabled by default.
Enable it (PowerShell as Administrator, just paste to avoid execution policy dance):
# Set the service to start automatically
Set-Service ssh-agent -StartupType Automatic
# Start it now
Start-Service ssh-agent
# Verify it's running
Get-Service ssh-agent
⚠️ Back to regular user shell. No more Administrator.
Generate your key WITHOUT a passphrase:
ssh-keygen -t ed25519 -C "your-hostname-2026-02-17"
When prompted for passphrase, press Enter twice (no passphrase).
Yes, this is 100% best practice, according to both me and Microsoft: https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_keymanagement - read on.
Add your key to the agent:
ssh-add ~/.ssh/id_ed25519
The key is now stored persistently - it will survive reboots, logouts, everything.
Security best practice:
.ssh/id_ed25519 (private key) into your password manager as secure note if you need it to survive your next SSD crashdel .ssh\id_ed25519 or rm ~/.ssh/id_ed25519.ssh/id_ed25519.pub (you need the public key)The agent retrieves the key from encrypted Windows storage in RAM only. If someone steals your laptop without your Windows password, they can't access the key. Even if your hard drive is unencrypted. (Yeah yeah, I know you turned that off. Because build times. I get you.)
Benefits:
macOS Keychain stores your SSH key passphrase, not the key itself. The private key file must remain on disk. (Yeah, rare win for the Windows guys, give it to them.)
Add key to Keychain (one-time setup):
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
This stores the passphrase in Keychain. The key file stays at ~/.ssh/id_ed25519.
Configure auto-add on first use (add to ~/.ssh/config):
Host *
UseKeychain yes
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
Now when you reboot:
Or manually reload all keys after reboot:
ssh-add --apple-load-keychain
Linux ssh-agent typically starts with your desktop session and keys stay in memory until logout/reboot.
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
Keys clear on logout. To auto-add on login, add the above to ~/.bashrc or ~/.zshrc. You'll need your passphrase for the key later.
(Not much changed since Tatu wrote it in 1995. File manager still snappy in 2026, though - Windows devs stay jealous.)
Create or edit ~/.ssh/config:
Host your-server-alias
HostName remote-host.example.com
User your_remote_user
IdentityFile ~/.ssh/id_ed25519
# For local hosts, you can skip HostName:
Host pi 192.168.1.100
User pi
IdentityFile ~/.ssh/id_ed25519
Now ssh your-server-alias will:
Mac/Linux:
ssh-copy-id -i ~/.ssh/id_ed25519.pub your-server-alias
Windows:
Windows OpenSSH doesn't include ssh-copy-id, but you can create a simple batch file to do the same thing.
Create %USERPROFILE%\.ssh\ssh-copy-id.bat:
@echo off
if "%1"=="" (
echo Usage: ssh-copy-id.bat user@remote-host
exit /b 1
)
type %USERPROFILE%\.ssh\id_ed25519.pub | ssh %1 "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
if %errorlevel% equ 0 (
echo.
echo Public key copied successfully to %1
echo Try: ssh %1
) else (
echo.
echo Failed to copy public key. Check connection and try again.
)
Then use it:
cd %USERPROFILE%\.ssh
ssh-copy-id.bat your-server-alias
This creates the .ssh directory with correct permissions, appends your public key, and sets file permissions.
Manual method (works everywhere):
If you prefer to do it by hand:
# 1. Display your public key (copy this output)
cat ~/.ssh/id_ed25519.pub
# Windows: type %USERPROFILE%\.ssh\id_ed25519.pub
# 2. SSH to remote server (password prompt)
ssh your-server-alias
# 3. On the remote server, paste your public key:
mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo "paste-your-public-key-here" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
exit
Test: ssh your-server-alias should connect without password prompt.
Consider disabling password authentication on the server now that you have working SSH key authentication. See Mozilla's OpenSSH hardening guide for a comprehensive reference.
If you get "no matching host key type found" when connecting to an older server, add this to your ~/.ssh/config:
Host old-server
HostName 192.168.1.50
User youruser
IdentityFile ~/.ssh/id_ed25519
HostKeyAlgorithms +ssh-rsa
PubkeyAcceptedAlgorithms +ssh-rsa
Modern OpenSSH disabled ssh-rsa by default (SHA-1 weakness). The + adds it back for that specific host without weakening your other connections.
Better fix: Upgrade the remote server's OpenSSH if you can. But if you're connecting to a NAS, router, or ancient enterprise box, sometimes you're stuck with the workaround.
If connecting from Windows to servers running OpenSSH < 8.5 (common in older VMs or appliances), you might see key exchange failures. Add to ~/.ssh/config:
Host old-server
KexAlgorithms -sntrup761x25519-sha512@openssh.com
This disables the post-quantum algorithm (default in modern Windows OpenSSH) for that server while keeping other secure KEX methods. You can also go with a pattern like Host 192.168.0.*
SSH agent setup is 10 minutes once, saves hours over time. Essential for:
Benefits of doing this now instead of scrolling on?