# SSH keys

> Create an SSH key on macOS, Linux or Windows, copy its public half into the console, and fix the permission errors that block a connection.

A machine accepts the public half of your key. The private half stays on your computer and never leaves it.

## Check for a key you already have

```bash
ls ~/.ssh/*.pub
```

A file such as `id_ed25519.pub` means you have a key. Skip to [Copy the public key](#copy-the-public-key).

## Create a key

### macOS and Linux

Open Terminal:

```bash
ssh-keygen -t ed25519 -C "you@laptop"
```

Press Enter to keep the default path (`~/.ssh/id_ed25519`). Add a passphrase: it protects the key if your computer is lost.

### Windows 10 and 11

OpenSSH ships with Windows. Open **PowerShell**:

```powershell
ssh-keygen -t ed25519 -C "you@laptop"
```

The key is written to `C:\Users\<you>\.ssh\id_ed25519`. If `ssh-keygen` is not found, open **Settings**, **System**, **Optional features**, and add **OpenSSH Client**.

## Copy the public key

Copy the single line of the `.pub` file and paste it in the launch form.

| System | Command |
|---|---|
| macOS | `pbcopy < ~/.ssh/id_ed25519.pub` |
| Linux | `cat ~/.ssh/id_ed25519.pub` |
| Windows | `Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub \| Set-Clipboard` |

The line starts with `ssh-ed25519`, `ecdsa-sha2-nistp256` or `ssh-rsa`. A block that starts with `-----BEGIN` is the private key: never paste it anywhere.

## Keys for scripts and agents

A session launched with an API key receives the public key sent with the launch. That key opens this session only and is not saved on your account. The CLI, the SDKs, the MCP server and the GitHub Action send it for you.

A key with the `workloads:read` scope lists the keys saved in the console, and a launch can name one of them. Saving or removing a key on your account is done in the console.

## Connect with this key

```bash
ssh -i ~/.ssh/id_ed25519 ubuntu@203.0.113.42
```

On Windows:

```powershell
ssh -i $env:USERPROFILE\.ssh\id_ed25519 ubuntu@203.0.113.42
```

To skip `-i` every time, add an entry to `~/.ssh/config`:

```text
Host nodelodge-*
  User ubuntu
  IdentityFile ~/.ssh/id_ed25519
```

## Load the key once per session

With a passphrase, the agent asks for it once:

```bash
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
```

On Windows, start the agent service once from an administrator PowerShell, then add the key:

```powershell
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519
```

## Fix permission errors

**`UNPROTECTED PRIVATE KEY FILE` or `bad permissions`**

SSH refuses a private key that other accounts can read.

macOS and Linux:

```bash
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
```

Windows:

```powershell
icacls $env:USERPROFILE\.ssh\id_ed25519 /inheritance:r /grant:r "$($env:USERNAME):(R)"
```

**`Permission denied (publickey)`**

- The key you pasted is not the one SSH offers. Pass it with `-i`.
- Connect as `ubuntu`, not `root`.
- A key pasted with a line break inside it does not match. Copy it again with the command above.

More connection errors: [Connect over SSH](https://nodelodge.com/docs/connect-ssh#troubleshooting).