How to Configure Claude Code SSH Guardrails

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up claude code ssh guardrails by combining local tool approvals with strict remote host permissions. This approach stops the AI agent from running risky commands on your remote servers. Most teams start by giving the agent a standard local SSH key for server tasks. If that key has broad Linux permissions, one bad prompt can break production systems. How claude code ssh guardrails work in practice Claude Code reaches external systems through its local Bash tool or Model Context Protoco

Claude Code Security + SSH Access Management: 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 guardrails by combining local tool approvals with strict remote host permissions. This approach stops the AI agent from running risky commands on your remote servers. Most teams start by giving the agent a standard local SSH key for server tasks. If that key has broad Linux permissions, one bad prompt can break production systems.

How claude code ssh guardrails work in practice

Claude Code reaches external systems through its local Bash tool or Model Context Protocol servers. When the agent needs to check a remote host, it invokes the Bash tool. In Manual mode, the Bash tool asks for human approval before running most shell commands. Only a small built-in set of read-only local commands runs without a manual prompt. Once you approve an SSH command, the agent uses your local SSH client and keys.

To tighten host entry, teams replace static public keys with OpenSSH user certificates. A certificate Authority key signs a user public key to create an OpenSSH certificate. This certificate holds identity data, valid principal names, and specific options in a simple format. You set a validity window when signing so the certificate expires after a short time. If you omit the validity window, the certificate stays valid forever by default. You can also embed certificate options that restrict which command the remote session can run.

Where native permissions fall short during live sessions

Local prompts and OpenSSH certificates solve the initial login problem well. They check who can log in and when that user key expires. Still, neither control watches what happens inside an active shell session after login. Once you approve the initial SSH command locally, the remote shell runs on the host. The local agent approval rule cannot parse complex shell scripts sent over that remote channel.

On the server side, Linux user roles apply to the whole account. If the agent logs in as an admin user, it can edit files or restart services. Restricting an OpenSSH certificate to one forced command helps for single checks. Yet debugging real incidents requires running many different read commands across logs and processes. Teams also struggle when server outputs return raw emails, phone numbers, or card numbers. Standard SSH setups pass those sensitive strings straight back into the model context window.

Claude Code Security + SSH Access Management: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Building safer workflows for AI server tasks

Start by separating human admin accounts from the accounts your coding agent uses. Create a dedicated Linux user on target hosts with read-only permissions on log folders. Do not give this user account sudo rights or write permissions on app folders. Next, keep Claude Code in Manual mode so you review every Bash tool call. Check the exact target host and command string before you let the command run.

Finally, use short validity windows on your OpenSSH user certificates for every agent task. When the task finishes, the signed certificate expires and stops working on the host. While these steps shrink the blast radius, they still require manual key and role work. Teams that run agents across dozens of hosts need fine-grained command checks and output masking.

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 server?

Claude Code runs SSH commands by calling its local Bash tool or an MCP server. In Manual mode, the Bash tool waits for your approval before opening the remote session.

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

Yes, OpenSSH certificates can set principal names, validity times, and command options. Still, forced command options work best for single tasks rather than open-ended debugging sessions.

Why is a read-only Linux user not enough for AI agents?

A read-only Linux user stops file changes, but it can still read sensitive app logs. Those logs often hold emails, phone numbers, or card numbers that enter the model prompt.

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.