Generating SSH Keys

An SSH key is a pair of files that together replace a password when you log in to a server. The private key stays on your computer - treat it like the key to your front door. The public key is the half you hand out: paste it into the portal, drop it into servers you want to log in to, share it freely.

This page walks you through making the pair on your own machine. Once you have one, see Adding an SSH Key to register the public half with your portal account.

You don't need to be in the portal yet - this is all done on your computer in a terminal. But first, check whether you already have a key from some earlier project.

1. Open a terminal.

   1. macOS: open Terminal (Applications > Utilities > Terminal) or iTerm.
   2. Linux: open whichever terminal emulator you normally use.
   3. Windows: open PowerShell or Windows Terminal from the Start menu.
2. List the contents of your SSH folder: On macOS or Linux: ls ~/.ssh/ On Windows (PowerShell): ls $env:USERPROFILE\.ssh\
3. Look at what comes back.

   1. If you see a pair like id_ed25519 and id_ed25519.pub, you already have a modern key - skip straight to "Print your public key" below.
   2. If you see id_rsa and id_rsa.pub, you have an older RSA key. It will still work, but consider generating a fresh Ed25519 one alongside it.
   3. If you see "No such file or directory" or the folder is empty, you've never made one - keep reading.

You'll use a tool called ssh-keygen that ships with every modern OS. The recommended key type is Ed25519 - it's faster, the public key is shorter, and it's at least as secure as RSA. Only use RSA if some old system specifically demands it.

1. In your terminal, run: ssh-keygen -t ed25519 -C "[email protected]" The -t ed25519 part picks the key type. The -C "[email protected]" part adds a comment so future-you can tell keys apart later - the email convention is just a habit; you can put anything in there, like "work laptop", "home desktop 2026", or a machine name.
2. First prompt - file path. ssh-keygen asks where to save the key. Press Enter to accept the default path (~/.ssh/id_ed25519). Only change this if you already have a key with that name and don't want to overwrite it.
3. Second prompt - passphrase. Type a passphrase. This is strongly recommended.

   1. The passphrase encrypts the private key on disk. If someone steals your laptop, they still can't use the key without the passphrase.
   2. Make it long - a sentence or three random words is fine.
   3. The cursor doesn't move as you type. That's normal; the characters are hidden on purpose.
4. Third prompt - confirm passphrase. Type the same passphrase again, then press Enter.
5. ssh-keygen prints a fingerprint and a "randomart" picture. You don't need to do anything with these - they're identifiers you'll only ever see again if you re-inspect the key.

You now have two new files in ~/.ssh/:

• id_ed25519 - your private key. Treat it like a password. Never paste it into chat, email, screenshots, or the portal.
• id_ed25519.pub - your public key. Safe to share.

Windows 10 and 11 ship ssh-keygen as part of OpenSSH. The command is identical:

1. Open PowerShell.
2. Run: ssh-keygen -t ed25519 -C "[email protected]"
3. Follow the same three prompts as above - Enter for the default path, type a passphrase, confirm it.

Files land in C:\Users\<your username>\.ssh\.

If you're using PuTTY instead of OpenSSH:

1. Open PuTTYgen from the Start menu.
2. Under "Type of key to generate", choose EdDSA, and set the curve to Ed25519.
3. Click Generate and wiggle the mouse over the empty area until the progress bar fills.
4. Type a passphrase into the Key passphrase and Confirm passphrase fields.
5. Click Save private key and save it as something like id_ed25519.ppk.
6. The long line in the box labelled Public key for pasting into OpenSSH authorized_keys file is your public key. That's what you'll paste into the portal.

If some system explicitly requires RSA, use at least 4096 bits:

ssh-keygen -t rsa -b 4096 -C "[email protected]"

The output filename is id_rsa.pub. Everything else  (the prompts, the passphrase, the safety rules) works the same way.

You'll need the public key as one long line of text to paste into the portal. Use the command that matches your OS.

macOS - copy straight to clipboard:

pbcopy < ~/.ssh/id_ed25519.pub

Or print it to the terminal so you can copy it manually:

cat ~/.ssh/id_ed25519.pub

Linux - print it:

cat ~/.ssh/id_ed25519.pub

If xclip is installed (X11):

cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard

If wl-copy is installed (Wayland):

cat ~/.ssh/id_ed25519.pub | wl-copy

Windows (PowerShell) - copy straight to clipboard:

Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard

Whichever command you use, the output looks like:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… [email protected]

That whole line - starting with ssh-ed25519 (or ssh-rsa for an RSA key), the long random-looking string in the middle, and the comment at the end - is your public key. The portal expects exactly this format: one line, including the leading algorithm and the trailing comment. No line breaks.

With the public key copied, head over to Adding an SSH Key to paste it into your account.

A few habits worth picking up:

• Never paste the private key anywhere. Not into the portal, not into a chat message, not into a screenshot. The portal will never ask for it.
• Back up ~/.ssh/ with whatever you back up your home directory with (Time Machine, restic, rsync to a NAS, etc.). Losing the private key locks you out of every server you've deployed it to.
• Rotate if it might have leaked. If you ever suspect the private key has been exposed (a stolen laptop, a suspect backup drive) generate a fresh pair, register the new public key in the portal, edit ~/.ssh/authorized_keys on every server it's deployed to, then delete the old one. SSH keys are designed to be rotated; don't hesitate.