Generate an Ed25519 SSH key and load it on macOS

Run ssh-keygen -t ed25519, accept the default path, set a passphrase, then add the key to ssh-agent with the macOS keychain option so you are not prompted every time. The steps below follow GitHub's current guide, with notes on the errors people hit.

Step 1: generate the key

ssh-keygen -t ed25519 -C "your_email@example.com"

Accept the default file location and choose a passphrase. GitHub gives an RSA 4096 bit command for legacy systems that lack Ed25519 support. If your system is recent, you will not need it.

Step 2: start the agent

eval "$(ssh-agent -s)"

Step 3: tell SSH to use the keychain

Create ~/.ssh/config if it does not exist, then add this block.

Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Omit the UseKeychain line if your key has no passphrase, though you should reconsider that, as covered in SSH key passphrase and ssh-agent.

If you get a Bad configuration option: usekeychain error, add an IgnoreUnknown UseKeychain line under the Host block. This happens when the SSH client in use does not know that option.

Step 4: add the key to the agent

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

GitHub notes that on macOS versions before Monterey (12.0) the equivalent flags were -K to store and -A to load. It also says to use Apple's built in ssh-add, not a Homebrew or MacPorts build. If you are still prompted for the passphrase after a restart, add the command to your shell startup file such as ~/.zshrc.

Step 5: register the public key

Upload the contents of the .pub file to your Git host, not the private file. Never paste the private key anywhere. A quick sanity check is that the public file starts with the key type and is a single line.

Common mistakes

• Sharing one key across machines. A lost laptop then forces a rotation everywhere. Generate one key per device.
• Emailing or chatting the private key to yourself. Treat the file as a secret from day one.
• Using a blank passphrase on a laptop. Disk encryption helps, but the key file is still readable once you are logged in.
• Forgetting the old keys. Remove retired keys from your Git host. GitHub lists them under Settings, SSH and GPG keys.

Next step

If you push commits often, consider using the same style of key to sign your commits. For stronger protection, move to a hardware backed key.

Quick check

Sources

• Generating a new SSH key and adding it to the ssh-agent, GitHub Docs

Last reviewed: 19 October 2026.