Setting Up SSH Keys on a Mac

Password authentication for SSH works, but for a server exposed to the internet, it is the weakest link. Passwords get reused, phished, and brute-forced by bots that scan port 22 continuously. Key authentication removes all three problems and is faster to use.

The whole process takes about five minutes.

How key authentication works

You generate a key pair: a private key that never leaves your Mac, and a public key that is safe to hand out. You append the public key to ~/.ssh/authorized_keys on the server.

At login, the server sends a random challenge; your client signs it with the private key; the server verifies the signature against the public key it already has. Your private key is never transmitted, so there is nothing on the wire for an eavesdropper to capture.

Generate a key

Use ed25519. It is smaller, faster, and stronger than RSA at equivalent security, and it has been the sensible default for years:

ssh-keygen -t ed25519 -C "carlo@macbook"

Accept the default location (~/.ssh/id_ed25519) and set a passphrase. The passphrase encrypts the private key on disk. macOS can remember it in the Keychain, so you only type it once.

You now have two files:

~/.ssh/id_ed25519        ← private. Never share, never copy to a server.
~/.ssh/id_ed25519.pub    ← public. This is the one you install.

If your server is old enough to reject ed25519, generate -t rsa -b 4096 instead. Upshell supports both ed25519 and ECDSA keys natively.

Install the public key on the server

If you have password SSH access, one command does it:

ssh-copy-id deploy@example.com

If ssh-copy-id is not available, copy the contents of the .pub file and append it as a single line to ~/.ssh/authorized_keys on the server, then fix the permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Test it before changing anything else:

ssh -i ~/.ssh/id_ed25519 deploy@example.com

If that logs you in without asking for the account password, the server side is done.

Using the key from a Mac client

Here is where macOS adds a wrinkle worth understanding rather than fighting.

Upshell is sandboxed, the same security model the Finder and every App Store app runs under. A sandboxed app cannot read arbitrary paths, and ~/.ssh is very much an arbitrary path — it cannot silently rummage through your private keys, which is precisely the point.

So the first time a site needs a key, Upshell asks you to select the file with a standard open panel. That grant is what authorizes access; from then on, the key material is stored in your Keychain and the connection works without prompting. The passphrase, if you set one, is stored alongside it.

This is also why importing ~/.ssh/config brings in the path of each IdentityFile rather than the key itself — the path is a note about which key to ask for, and you authorize it once at first connection.

To set it up: open the site editor, pick the identity from the Key Manager picker (under settings ⌘,), and connect.

Turning off password login

Once keys work for every account you use, disable password authentication entirely.

In /etc/ssh/sshd_config on the server:

PasswordAuthentication no
PubkeyAuthentication yes

Then reload the SSH daemon. Keep your existing session open while you test a new connection in a second window — if something is wrong, you want a way back in.

Step by step

1. Generate an ed25519 key pair with ssh-keygen -t ed25519 -C "your-note", and set a passphrase when prompted.
2. Install the public key with ssh-copy-id user@host, or append the .pub contents manually.
3. Fix permissions on the server — chmod 700 ~/.ssh and chmod 600 ~/.ssh/authorized_keys, or SSH will ignore the file.
4. Test from the Terminal with ssh -i ~/.ssh/id_ed25519 user@host first.
5. Point the client at the key — in Upshell, import the key via the Key Manager. macOS sandboxing means this grant is explicit, and it is then kept securely in the Keychain.
6. Disable password authentication on the server, testing in a second session before closing the first.

Questions people ask

Which key type should I use, ed25519 or RSA?

ed25519 unless the server is too old to accept it. It is faster, keys are far shorter, and its security margin is excellent. Upshell supports ed25519 and ECDSA.

Do I need a passphrase on the key?

Strongly recommended. Without one, anyone who obtains the file — from a backup, a synced folder, a stolen laptop — has your server. With one, the file alone is useless.

Why does the app ask me to pick the key file instead of finding it?

Because it is sandboxed and cannot read ~/.ssh without your explicit consent. That is a security property, not a limitation: the same rule stops any App Store app from quietly reading your private keys.