← All Posts

How to Do SSH Key Setup on Claude Code

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 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:

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

ed25519 is the recommended algorithm by GitHub 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:

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:

pbcopy < ~/.ssh/id_ed25519.pub

Then go to GitHub SSH key settings, paste the key, and save. Verify the connection:

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 or custom deploy scripts). The setup is the same: copy your public key to the server's ~/.ssh/authorized_keys:

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

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

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:

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.

Keep your session going: monitor Claude Code usage while you work

SSH setup is a one-time task, but Claude Code usage limits are an ongoing concern. If you are deep in a multi-step task (setting up infrastructure, fixing a CI pipeline, pushing several branches) and your usage window resets mid-task, you get locked out for up to 5 hours.

Usagebar sits in your macOS menu bar and shows your current Claude Code usage at a glance, with smart alerts at 50%, 75%, and 90% so you can plan around the reset window. Credentials are stored in macOS Keychain, matching the same secure approach you use for SSH keys. It is free for students and uses a pay-what-you-want model.

You can also check usage anytime with the /usage command in Claude Code, or at claude.ai/settings/usage. But for staying in flow without tab-switching, Usagebar is the faster option.

Learn more about when Claude Code usage resets and how to check your usage limits to avoid interruptions during critical tasks.

Get Usagebar and know exactly where you stand before starting your next big push.

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 or /usage so a usage reset does not interrupt a long agentic task.

Related guides

Sources

Track Your Claude Code Usage

Never hit your usage limits unexpectedly. Usagebar lives in your menu bar and shows your 5-hour and weekly limits at a glance.

Get Usagebar