// ssh config

IdentitiesOnly yes: stop SSH from trying every key

By default SSH offers every key in your agent, not just the one you configured. One line changes that, and it fixes a surprising number of SSH mysteries.

Updated · 2 min read · by Pixel Worship, LLC

#The problem it solves

Every time you connect, SSH builds a list of keys to try:

  1. Keys named by IdentityFile in matching config blocks (or -i on the command line).
  2. 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

~/.ssh/config
Host github.com
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

With 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

Terminal
ssh -vT git@github.com 2>&1 | grep "Offering public key"

Without IdentitiesOnly:

Output
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:… agent

With 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:

~/.ssh/config
Host github.com
  IdentityFile ~/.ssh/github_1password.pub
  IdentitiesOnly yes

#One-off use on the command line

Terminal
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.