How to Configure Claude Code SSH Least Privilege

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up claude code ssh least privilege by scoping local shell rules and remote keys. You also limit which commands and users the agent can run on each host. Most teams start by giving the coding agent their own local SSH keys. That mistake grants the AI full admin rights across every server the developer can reach. If a prompt goes wrong, the agent can delete files or change live apps. How claude code ssh least privilege works Claude Code reaches remote machines in two main ways. First, i

Least Privilege Principle + Claude Code Security: 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 least privilege by scoping local shell rules and remote keys. You also limit which commands and users the agent can run on each host. Most teams start by giving the coding agent their own local SSH keys. That mistake grants the AI full admin rights across every server the developer can reach. If a prompt goes wrong, the agent can delete files or change live apps.

How claude code ssh least privilege works

Claude Code reaches remote machines in two main ways. First, it runs shell commands through its built-in Bash tool. In Manual mode, the Bash tool asks for human approval before running most commands. Only a small built-in list of read-only commands runs without a prompt. Second, the agent can talk to external tools through Model Context Protocol servers.

When the Bash tool runs an SSH command, it uses the local system keys. To apply claude code ssh least privilege, you must separate agent keys from human keys. Never let the agent use a key that has full root rights. Instead, create a dedicated Linux user on the target host with read-only group permissions.

Next, replace static public keys with OpenSSH user certificates. OpenSSH added certificate support in version 5.4 to simplify key signing. A certificate authority key signs a public key and embeds identity info. It also lists allowed principal names and specific options in a simple format. You set a short validity window when signing so the certificate expires fast. If you skip the validity setting, the certificate stays valid forever by default. You can also bake a fixed command option right into the certificate. That rule forces the remote host to run only one set script during login.

What native SSH controls solve and what they miss

Native OpenSSH certificates and restricted Linux users solve the initial login problem. They stop the agent from logging in as root or holding permanent keys. Local Manual mode in Claude Code also helps by asking you to approve commands. Together, these steps shrink the blast radius of a bad command on a host.

Still, native SSH setup only checks who logs in at the start. Once the session opens, SSH does not inspect the commands or output inside the tunnel. If you allow a general shell, the agent can still read secret files. It can also dump customer emails, phone numbers, or card numbers into the terminal. Those raw values then flow straight back into the model context window.

Least Privilege Principle + Claude Code Security: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Locking a key to one forced script has limits too. Real debugging needs flexible read commands across logs, processes, and app folders. Maintaining dozens of custom wrapper scripts across every host takes hours of manual work. Teams also lack a central log that ties each remote command to a developer identity. Standard SSH logs show the shared Linux user name, not the person running the agent.

Steps to lock down agent host sessions

Start by keeping Claude Code in Manual mode for all Bash tool calls. Review every remote command before you let the agent run it. Do not add the SSH binary to an automatic allow list on your workstation.

On the remote server, build a locked-down Linux user just for diagnostics. Give that user read access to log folders and nothing else. Block port forwarding and agent forwarding in your OpenSSH certificate options. Sign each user certificate for a single task and set it to expire in minutes. When the agent finishes checking the server, revoke or delete the temporary key right away.

Check SSH commands and file transfers on the host

OpenSSH keys and certificates decide who can log into a Linux host. They do not check what a one-shot command or file transfer does once the session starts. With hoop.dev, you run an open-source SSH server with guardrails inline on the host. On every one-shot command or file transfer an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.

When a caller runs a one-shot command or moves a file, hoop.dev guardrails check the command or path before it runs, and hoop.dev data masking masks matched sensitive patterns in downloads and output. Interactive shells carry no guardrails because keystrokes have no statement boundary. Teams can turn interactive shells off and allow only commands and file tasks. The audit trail logs who connected and what was allowed or refused, without storing keystrokes or file bytes. See the source on GitHub.

Frequently asked questions

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

Claude Code runs SSH commands through its built-in Bash tool or through an MCP server. In Manual mode, the Bash tool asks for your approval before opening the remote session.

Why are OpenSSH certificates better than static keys for coding agents?

OpenSSH certificates hold signed identity info, allowed user names, and options in one small file. You can set a short time limit when signing so the agent key expires on its own.

Does a read-only Linux user stop sensitive data from reaching the AI model?

No, a read-only user still lets the agent read files and print them to the screen. If log files hold emails, phone numbers, or national IDs, that data enters the model context.

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.