SSH Config Files on Mac: How to Write and Organize Yours

Quick answer

Your SSH config file is a plain-text file at ~/.ssh/config that you create yourself — macOS doesn't ship one for you. It replaces long commands like ssh -i ~/.ssh/id_ed25519 -p 2222 user@203.0.113.5 with a short alias (ssh myserver) and lets you set per-host defaults for hostname, port, username, and which key to offer. macOS checks ~/.ssh/config before the system-wide `/etc/ssh/ssh_config`; for any setting that appears in both, the first value SSH finds wins.

It's one of several small text files worth getting comfortable with — see our guide to editing config files and dotfiles on Mac and iOS for the broader picture.

Step-by-step

Create the file and directory with the right permissions

SSH is strict about who can read your config. Set this up before anything else:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
touch ~/.ssh/config
chmod 600 ~/.ssh/config

Open it in Terminal with nano ~/.ssh/config or another plain-text editor — not TextEdit's default rich-text mode, which saves an .rtf file that SSH silently won't recognize as a valid config. Not sure what got saved? file ~/.ssh/config should report "ASCII text," not "rich text."

Learn the basic syntax

A config file is a series of Host blocks, each one a keyword-argument pair per line:

Host myserver
  HostName 203.0.113.5
  User alice
  Port 2222
  IdentityFile ~/.ssh/id_ed25519

Host is the alias you type on the command line. HostName is the real address, User and Port override the defaults, and IdentityFile points at the private key to offer. Patterns after Host also support wildcards: * matches any number of characters, ? matches exactly one, and a leading ! negates a pattern. That means a block like Host * near the top of the file can set defaults that every entry below inherits, per the OpenSSH spec. As the file grows, an Include line can pull in separate config files — one per project or client — instead of stacking everything into a single sprawling document.

Wire it into the macOS Keychain

If your key has a passphrase, add AddKeysToAgent and UseKeychain to skip retyping it every session. This has worked since macOS Sierra 10.12.2:

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

AddKeysToAgent loads the key into ssh-agent automatically on first use. UseKeychain stores the passphrase in the macOS Keychain instead of asking every time. Leave UseKeychain out entirely if your key has no passphrase, and add IgnoreUnknown UseKeychain to the same block if you ever run this config against an older, non-macOS SSH client that doesn't recognize the option.

Organize multiple accounts and servers

The pattern that scales is one uniquely named Host alias per account or server, each with its own IdentityFile:

Host github-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_personal
  IdentitiesOnly yes

Host github-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_work
  IdentitiesOnly yes

Both blocks point HostName at the same github.com. But the aliases — github-personal, github-work — are what you actually type; git remote URLs and ssh commands reference the alias, not the literal hostname. IdentitiesOnly yes tells SSH to offer only the key listed in that block, which is what keeps the two accounts from crossing wires.

Common problems and fixes

• SSH authenticates as the wrong account. This almost always means two IdentityFile lines are stacked under one wildcard Host block instead of split across separate aliases. IdentityFile entries inside a matching block accumulate rather than replace each other, so SSH offers every key it finds — including the one you didn't intend. The fix is the alias-per-account pattern above, each with IdentitiesOnly yes.
• "Bad owner or permissions" error. The .ssh directory or the config file itself is more permissive than SSH allows. Re-run chmod 700 ~/.ssh and chmod 600 ~/.ssh/config.
• The file seems to do nothing. Confirm it's plain text, not .rtf, and confirm it's actually at ~/.ssh/config — a typo'd path or a file saved to ~/Desktop/config won't be read.
• The config is getting hard to navigate. Split it by project or client with Include, and keep the non-secret parts — aliases, hostnames, ports, never private key contents — under version control. Our guide on version-controlling plain-text files with Git covers the same workflow for notes, and it applies just as well to dotfiles.

Frequently Asked Questions

Where is the SSH config file on Mac?

Your personal SSH config file lives at ~/.ssh/config. It doesn't exist by default — you create it yourself as a plain-text file. macOS also reads a system-wide file at /etc/ssh/ssh_config, but ~/.ssh/config is checked first and wins whenever the same setting appears in both.

What permissions should ~/.ssh/config have?

Create the .ssh directory with chmod 700 and the config file itself with chmod 600, so only your account can read or write it. SSH can silently ignore or reject a config file that's more permissive than that.

Can I use different SSH keys for different GitHub accounts?

Yes — give each account its own Host alias (not just github.com twice) with a single IdentityFile and IdentitiesOnly yes per block. Stacking multiple IdentityFile lines under one wildcard Host is the most common way people accidentally authenticate as the wrong account.

Do I need UseKeychain on every Mac?

UseKeychain only matters if your key has a passphrase and you're on macOS Sierra 10.12.2 or later — it tells SSH to store that passphrase in the macOS Keychain instead of asking every time. If your key has no passphrase, leave the line out entirely.

Doing this with Carets

Once ~/.ssh/config exists, it's just another small plain-text file you'll reopen often — a new Host block for a server you just spun up, a Port you need to tweak, an alias you want to rename. Carets opens and edits files like this with syntax highlighting for config-style text, so Host, HostName, and IdentityFile lines are easy to scan instead of running together as flat text. Files, projects, and tags keep a config file next to related notes and READMEs instead of buried in a folder you never open. And since Carets is native and fast on iPhone, iPad, and Mac, a quick edit doesn't require pulling out a laptop. If you keep a small library of reusable Host blocks, our piece on keeping snippets and config in plain text files covers that pattern directly.

Carets is available on the App Store for iPhone, iPad, and Mac.