How to Configure Claude Code SSH Credentials

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up claude code ssh credentials by giving the agent local keys or MCP servers. The agent then uses its Bash tool or Model Context Protocol servers to reach remote hosts. Most teams start by pointing the agent at a standard developer key on the laptop. This works fast for testing, but it gives the agent broad rights across every server. If the agent makes a mistake, it can change files or drop data right away. How claude code ssh credentials work in practice Claude Code reaches remote m

Claude Code Security + Ephemeral Credentials: the complete guide

Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.

Free white paper. No spam. Unsubscribe anytime.

You set up claude code ssh credentials by giving the agent local keys or MCP servers. The agent then uses its Bash tool or Model Context Protocol servers to reach remote hosts. Most teams start by pointing the agent at a standard developer key on the laptop. This works fast for testing, but it gives the agent broad rights across every server. If the agent makes a mistake, it can change files or drop data right away.

How claude code ssh credentials work in practice

Claude Code reaches remote machines through two main paths on your local workstation. First, it can run standard shell commands through its built-in Bash tool. Second, it can talk to external tools and APIs through Model Context Protocol servers. When the agent runs a shell command, it inherits your local terminal setup and keys. In manual mode, the Bash tool asks for your approval before it runs remote commands. It only skips approval for a small built-in list of safe local read commands.

If you use a local SSH agent, the coding tool uses those loaded keys. You can also set up an OpenSSH certificate instead of a plain static key. Since OpenSSH 5.4, the key tool can sign a public key with a certificate authority. A signed user certificate holds a public key, an identity string, and valid user names. It also holds extra options that the authority signs to restrict the login session. The remote server checks the authority signature instead of looking up single public keys. This approach helps teams avoid leaving static private keys on developer laptops forever.

What native SSH setup solves and what it misses

Native OpenSSH keys and certificates do a great job of proving who can log in. They verify the user identity and establish an encrypted tunnel to the remote host. You can also create a restricted Linux user on the target server with read-only rights. This matches the official advice for database connections, where docs suggest using a read-only user. A read-only OS user stops the agent from deleting system files or restarting services.

Still, native SSH setup only checks identity at the start of the login session. Once the tunnel is open, the SSH daemon does not inspect individual commands in flight. If the agent needs write rights to fix a bug, a read-only user will fail. If you grant write rights, the agent gets those full rights for the whole session. Approval prompts in manual mode help, but engineers often get tired and click approve fast. A single approved shell script can run many hidden steps on the remote server.

Claude Code Security + Ephemeral Credentials: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Why static keys create risks for AI agents

AI coding agents work fast and can chain together many commands in a few seconds. When you share your personal key with an agent, audit logs become very hard to read. The remote server log shows your username, not the specific task the agent was doing. Security teams cannot tell if a human typed a command or the agent generated it.

Also, local keys and MCP server configs often sit on disk in plain text files. If an agent reads project files, it might read sensitive keys or pass them into prompts. Also, standard SSH sessions return raw command output directly back to the AI model context. If a remote log file holds emails, phone numbers, card numbers, or national IDs, the model sees them. Native SSH has no built-in way to rewrite matched fields in results before they return. Teams need a safer way to control every command and filter sensitive output in flight.

Add command and file guardrails to SSH access

Host firewalls and certificate principals control who opens an SSH session. Yet an allowed user or agent can still run a bad one-shot command or pull sensitive files over sftp. In practice, hoop.dev sits inline on the host as an open-source SSH server with guardrails that uses OpenSSH certificates. For every one-shot command or sftp task an agent or human runs in production, hoop.dev decides to pass, mask, block, or escalate it for review.

Using hoop.dev SSH controls, guardrails check one-shot commands, env variable names, and sftp or scp paths before they run. Port forwards default to deny unless the target is listed. Because interactive shells have no statement boundary and carry no guardrails, teams can turn them off so every command is checked and logged. Check out the MIT-licensed project on GitHub.

Frequently asked questions

How does Claude Code run SSH commands on a remote host?

It runs SSH commands through its built-in Bash tool or through a configured MCP server. In manual mode, the Bash tool asks for user approval before running an SSH command.

Should I give an AI agent my personal SSH private key?

No, sharing your personal key gives the agent all of your server permissions at once. It also makes server audit logs unclear because every agent action looks like your own work.

Can OpenSSH certificates limit what an AI agent does on a server?

OpenSSH certificates can restrict which user principals can log in and set basic session options. Still, they cannot inspect or block individual shell commands after the SSH session starts.

Save the open-source gateway.

hoop is MIT-licensed infrastructure for controlling how AI agents reach production data. Star hoophq/hoop so you can inspect it, deploy it, or share it when your team starts governing agent access.