How to Configure Claude Code SSH Connect

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a claude code ssh connect workflow through its Bash tool or MCP. Both paths let the agent log in to remote hosts and run shell commands. Most teams start by pointing the agent at a local SSH client and key. This setup gets an agent onto a server fast, but broad permissions create big risks. If the user account has root rights, one bad prompt can break production. How a native claude code ssh connect workflow works Claude Code reaches external systems through two main paths. First,

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 a claude code ssh connect workflow through its Bash tool or MCP. Both paths let the agent log in to remote hosts and run shell commands. Most teams start by pointing the agent at a local SSH client and key. This setup gets an agent onto a server fast, but broad permissions create big risks. If the user account has root rights, one bad prompt can break production.

How a native claude code ssh connect workflow works

Claude Code reaches external systems through two main paths. First, it runs local shell commands through its built-in Bash tool. Second, it talks to outside tools and servers through the Model Context Protocol, or MCP. When you use the Bash tool, the agent calls the local OpenSSH client directly.

In Manual mode, the Bash tool asks for human approval before running most commands. It only skips approval for a small built-in list of safe read-only commands. Still, an SSH call opens a remote shell or passes a command string over the network. Once the local SSH command starts, the remote host relies on its own account rules.

To lock down the login step, many teams use OpenSSH certificates instead of static keys. OpenSSH added certificate support for users and hosts in version 5.4. A certificate Authority key signs a user public key to build a certificate. That certificate holds the public key, an identity string, principal names, and a set of options. It uses a much simpler format than X.509 certificates. Teams can also route traffic through a bastion or jump host to reach private networks.

Why native SSH keys and prompts leave a runtime gap

OpenSSH certificates and manual tool prompts solve the initial login problem well. They check who is allowed to reach the host before the session starts. If you use an MCP server instead, the vendor docs say to verify you trust it. Both methods focus on the start of the connection.

The gap appears after the login succeeds and the agent starts running commands. OpenSSH checks the key or certificate at the door, not each command inside the session. If the remote Linux user can write files or restart apps, the agent can too. Approving a single command in the local terminal does not filter the data coming back.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Remote logs and database dumps often hold live customer emails, phone numbers, or card numbers. Standard SSH sends that raw output straight back into the agent context window. Native SSH also lacks per-command approval rules tied to what happens inside the remote shell. Teams need a way to inspect commands in flight and rewrite sensitive fields in results.

Best practices for safer agent SSH sessions

Start by creating a dedicated Linux user on the target host just for the agent. Give that user read-only file permissions and remove all sudo rights. Never let the agent share a personal developer key with broad server rights.

Next, sign user keys with an OpenSSH Certificate Authority and set a short validity window. By default, OpenSSH certificates last forever unless you set a time limit when signing. Always set a tight expiration window and list exact principal names on the certificate. Keep the agent in Manual mode so a human reviews every shell call before it runs.

Inspect one-shot SSH commands and file tasks

SSH certificates and host rules decide who is allowed on a machine. Setup alone does not check single commands or block sftp reads on sensitive paths. By design, hoop.dev runs an inline open-source SSH listener on the host where engineers and AI agents keep their normal ssh, sftp, and scp tools. On every production command or file operation, hoop.dev decides whether to pass, mask, block, or hold it for approval.

First, hoop.dev guardrails check one-shot commands and file paths before they run, and hoop.dev data masking masks matched values in file downloads. The audit trail logs the certificate principal, requested action, and verdict without storing session content. Interactive shells carry no guardrails and can be turned off when every action must be checked. Explore the code on GitHub.

Frequently asked questions

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

It either calls the local SSH client through its Bash tool or uses an MCP server. In Manual mode, the Bash tool asks you to approve the command before it runs.

Can OpenSSH certificates limit which user an agent logs in as?

Yes, when you sign a user key, you list allowed principal names in the certificate. The remote host checks that the principal matches the requested login user before opening a session.

Does native SSH hide sensitive data from the AI agent?

No, standard OpenSSH sends all command output straight back to the client. If a log file holds emails or card numbers, that raw text enters the agent 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.