#The problem it solves
Every time you connect, SSH builds a list of keys to try:
- Keys named by
IdentityFilein matching config blocks (or-ion the command line). - Every key loaded in
ssh-agent, including ones added for other hosts weeks ago.
The server checks them one at a time. That causes three classic problems:
- Wrong account: GitHub accepts the first key that belongs to any account, so a personal key in the agent can win over your work key. (Multiple GitHub accounts)
- Too many attempts: servers disconnect after 6 failures by default. (Too many authentication failures)
- Noise in logs: every server you touch sees all your public keys.
#What IdentitiesOnly yes changes
Host github.com
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yesWith it, SSH only offers the identities you configured for that host. Agent keys that aren't named in the config are ignored.
It doesn't turn the agent off. If ~/.ssh/id_ed25519 is loaded in the agent, SSH still uses it through the agent, so you aren't asked for the passphrase again.
#Before and after
ssh -vT git@github.com 2>&1 | grep "Offering public key"Without IdentitiesOnly:
debug1: Offering public key: /Users/you/.ssh/id_ed25519 ED25519 SHA256:…
debug1: Offering public key: work@company ED25519 SHA256:… agent
debug1: Offering public key: deploy@ci RSA SHA256:… agentWith it, only the first line remains.
#When to use it
Use it on every host that has an IdentityFile. It's the line that makes "this host uses this key" actually true.
Be careful putting it in Host * if some hosts don't name a key: with IdentitiesOnly yes and no IdentityFile, SSH limits itself to its default files (~/.ssh/id_ed25519, ~/.ssh/id_rsa and so on) and ignores every other key in your agent.
#With 1Password, Secretive and other agents
Agent-based keys have no private file on disk. Point IdentityFile at the public key and SSH asks the agent for the matching private key:
Host github.com
IdentityFile ~/.ssh/github_1password.pub
IdentitiesOnly yes#One-off use on the command line
ssh -o IdentitiesOnly=yes -i ~/.ssh/deploy_ed25519 deploy@server.example.com#Set and forget
EasySSHConfig writes IdentitiesOnly yes into every host rule it manages, and shows .pub-only keys as "Agent-backed" so 1Password and Secretive keys can be assigned like any other.
Frequently asked questions
What does IdentitiesOnly yes do?
It makes SSH use only the identity files named in your config or on the command line (or the default key files if none are named), even when ssh-agent offers more keys.
Does IdentitiesOnly disable ssh-agent?
No. A configured key that's loaded in the agent is still used through the agent, so you aren't asked for its passphrase again. Only the agent's other keys are ignored.
Should I put IdentitiesOnly yes in Host *?
Only if every host you use has an IdentityFile. Hosts without one would be limited to SSH's default key files (like ~/.ssh/id_ed25519). Setting it per host alongside IdentityFile is the safest pattern.
Does it work with 1Password or Secretive?
Yes. Point IdentityFile at the key's .pub file. SSH then asks the agent for the matching private key and offers only that one.