How to Configure OpenHands SSH Guardrails

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up openhands ssh guardrails by pairing restricted Linux users with signed OpenSSH certificates. You also add runtime checks to inspect and filter shell commands before they run. Engineering teams often give AI agents a shared SSH key and a broad shell role. That shortcut lets an autonomous agent run bad commands, read private files, or break servers. A safe setup scopes the login identity and checks every command during the session. How to set up native openhands ssh guardrails Start

SSH Access Management + AI Guardrails: 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 openhands ssh guardrails by pairing restricted Linux users with signed OpenSSH certificates. You also add runtime checks to inspect and filter shell commands before they run. Engineering teams often give AI agents a shared SSH key and a broad shell role. That shortcut lets an autonomous agent run bad commands, read private files, or break servers. A safe setup scopes the login identity and checks every command during the session.

How to set up native openhands ssh guardrails

Start by creating a dedicated Linux user on the target host for the agent. Give this user read permissions only on the folders it needs to inspect. Do not add this account to the sudo group or give it root rights. Next, replace static public keys with OpenSSH user certificates signed by a Certification Authority key. OpenSSH added certificate support for users and hosts in release 5.4.

An OpenSSH certificate uses a much simpler format than a standard X.509 certificate. It holds a public key, an identity string, principal names, and signed options. When you sign the agent key, you set a clear key identity for your logs. You also list the exact principal names the agent can use to log in. Finally, you set a validity window so the certificate expires after a short task. If you skip the validity window, the certificate stays valid forever by default. You can also attach certificate options to limit port forwarding or force a set command.

Where native SSH controls fall short for AI agents

Native OpenSSH certificates and Linux user roles solve the login problem very well. They decide who can log in, which principal they use, and when keys expire. Still, native SSH rules stop working the moment the shell session starts. Once the agent opens a shell, the host trusts every command that user can run.

An AI agent works by writing and running new shell commands on the fly. You cannot lock the certificate to one fixed command if the agent needs to debug. With open shell permissions, a confused agent might delete app files or stop a service. It can also print logs that hold user emails, phone numbers, or card numbers. Standard SSH logs show that a session happened, not what each shell command returned. Teams have no built-in way to pause one risky command for human approval. They also lack a way to rewrite sensitive fields in command output before the agent reads them.

SSH Access Management + AI Guardrails: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Why runtime command checks matter for agent workflows

Fixing this gap requires moving controls from the login step to the command level. Instead of trusting a whole shell session, teams need to check each command in flight. Safe read commands like checking disk space or reading status logs can run right away. Risky write commands like restarting services or changing files should wait for a human check.

Output filtering is just as important when AI models read terminal text. When a command prints customer records, masking rules should rewrite matched fields in results. Rewriting emails, phone numbers, and national IDs keeps raw secrets out of model prompts. Pairing short-lived SSH logins with per-command checks gives agents room to work without risking outages.

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 on the host. It checks callers with OpenSSH certificates and works with ssh, sftp, scp, and rsync clients.

When a caller runs a one-shot command or moves a file, hoop.dev guardrails check the command or path before it runs. Then 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

Why are static SSH keys risky for OpenHands agents?

Static SSH keys do not expire on their own and often sit on agent workers. If an agent or container leaks that key, anyone can log into your servers. Signed OpenSSH certificates let you set a short validity window and a clear key identity.

Can Linux file permissions alone stop bad agent commands?

Linux permissions stop an agent from changing files owned by other system users. Still, the agent still needs write rights to do useful work in its own folders. Within those folders, Linux permissions cannot tell a good fix from a bad delete command.

How does data masking help during an agent SSH session?

Agents often read app logs or config files to find the root cause of bugs. Those files can hold user emails, phone numbers, card numbers, or national IDs. Masking rewrites matched fields in results before the text goes back to the AI model.

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.