SSH key setup in Claude Code lets you authenticate with GitHub, GitLab, and remote servers without typing passwords. Claude Code runs in your terminal and inherits your shell's SSH environment, so keys you configure in `~/.ssh/` are immediately available. If you use Claude Code for [Git commits](/content/blog/how-to-do-git-commits-on-claude-code/index.html) and deployments, SSH key auth is the most reliable, credential-free way to work.

- Works for any SSH-based remote: GitHub, GitLab, Bitbucket, custom servers
- Claude Code inherits the full macOS SSH agent, including keys loaded via Keychain
- No special Claude Code config needed once keys are in `ssh-agent`

## What is SSH key authentication and why use it with Claude Code?

SSH keys replace password-based authentication with a cryptographic key pair: a private key stored on your machine and a public key added to the remote host. When Claude Code runs shell commands, calls `git push`, or connects to a remote machine on your behalf, it uses the same SSH agent your terminal session has access to.

This matters especially for agentic workflows. When you ask Claude Code to push a branch, open a pull request, or run a remote deployment script, it needs a live, authenticated SSH connection. A missing key or an unloaded agent will interrupt the task mid-flow, exactly the kind of context switch you want to avoid.

## How to generate a new SSH key for Claude Code

Open your terminal (Claude Code runs inside it, so this is the same environment) and run:

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

`ed25519` is the [recommended algorithm by GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) for new keys: smaller, faster, and more secure than the older RSA defaults. When prompted for a file location, press Enter to accept `~/.ssh/id_ed25519`. Add a passphrase for security (macOS Keychain can store it so you never type it manually).

### Add the key to ssh-agent with macOS Keychain

Start the agent and add your key, using the `--apple-use-keychain` flag so macOS stores the passphrase:

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

Then add the following to `~/.ssh/config` to make this persistent across reboots:

```
Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519
```

With this config, Claude Code sessions always have access to your loaded key without any manual `ssh-add` step per session.

## How to add your public key to GitHub

Copy the public key to your clipboard:

```bash
pbcopy < ~/.ssh/id_ed25519.pub
```

Then go to [GitHub SSH key settings](https://github.com/settings/ssh/new), paste the key, and save. Verify the connection:

```bash
ssh -T git@github.com
```

You should see: `Hi username! You've successfully authenticated...`. Claude Code can now push and pull from any GitHub remote you have access to.

### Using multiple SSH keys for different hosts

If you work with multiple GitHub accounts or both GitHub and a private server, use `~/.ssh/config` to route keys by host:

```
Host github-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work

Host github-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal
```

Then clone using the alias: `git clone git@github-work:org/repo.git`. Claude Code will use the correct key automatically based on the remote URL in the repo's config.

## How to give Claude Code access to a remote server via SSH

Claude Code can run commands on remote machines if you ask it to use `ssh user@host` or tools that wrap SSH (like [Vercel CLI](/content/blog/how-to-do-vercel-deployment-on-claude-code/index.html) or custom deploy scripts). The setup is the same: copy your public key to the server's `~/.ssh/authorized_keys`:

```bash
ssh-copy-id user@your-server.com
```

If `ssh-copy-id` is not available, do it manually:

```bash
cat ~/.ssh/id_ed25519.pub | ssh user@your-server.com "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
```

After this, Claude Code can run remote commands without prompting for a password, keeping long agentic tasks uninterrupted.

## Troubleshooting SSH in Claude Code sessions

### Permission denied (publickey)

This usually means the key is not loaded into `ssh-agent`. Run `ssh-add -l` to check. If empty, run `ssh-add --apple-use-keychain ~/.ssh/id_ed25519`. Check that your `~/.ssh/config` has the `AddKeysToAgent yes` and `UseKeychain yes` lines.

### ssh-agent not running in Claude Code subshells

Claude Code spawns subshells to run commands. If `SSH_AUTH_SOCK` is not exported in your shell's `.zshrc` or `.bash_profile`, the agent socket may not be visible. Add this to your shell config:

```bash
export SSH_AUTH_SOCK=$(launchctl getenv SSH_AUTH_SOCK)
```

On macOS, the system SSH agent (managed by launchd) is the most reliable source and persists across sessions.

### Wrong key used for a host

Run `ssh -vT git@github.com` to see verbose output showing which key is being offered. Cross-check with your `~/.ssh/config` `IdentityFile` entries.

## Key takeaways

1. Generate an `ed25519` key with `ssh-keygen -t ed25519` and store the passphrase in macOS Keychain.
2. Add `AddKeysToAgent yes`, `UseKeychain yes`, and your `IdentityFile` to `~/.ssh/config` for persistent access.
3. Copy your public key to GitHub via the SSH settings page and verify with `ssh -T git@github.com`.
4. Use host aliases in `~/.ssh/config` to manage multiple keys cleanly.
5. Export `SSH_AUTH_SOCK` from launchd in your shell config so Claude Code subshells inherit the agent.
6. Monitor usage with [Usagebar](/content/site-root.html) or `/usage` so a usage reset does not interrupt a long agentic task.