How to Configure OpenHands SSH Credentials

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up openhands ssh credentials by passing a private key or certificate to the agent runtime. Then you register the matching public key or authority on your remote Linux servers. Teams often mount a static key from the host machine into the agent container. This lets the agent log in and run tasks across remote servers. Still, broad permissions let an autonomous agent change files or stop services on any target host. How openhands ssh credentials work in practice OpenHands runs inside an

Ephemeral Credentials + 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 openhands ssh credentials by passing a private key or certificate to the agent runtime. Then you register the matching public key or authority on your remote Linux servers. Teams often mount a static key from the host machine into the agent container. This lets the agent log in and run tasks across remote servers. Still, broad permissions let an autonomous agent change files or stop services on any target host.

How openhands ssh credentials work in practice

OpenHands runs inside an isolated container workspace where it plans and executes shell commands. When a task requires remote server changes, the agent uses standard OpenSSH client tools. It reads key files from its workspace or connects through a forwarded agent socket. The remote server checks the public key against its list of allowed users.

Relying on static key files creates key rotation work when agents run across many nodes. To improve this, teams often use OpenSSH certificates instead of raw public keys. A certificate Authority key signs a user public key to build a certificate. This certificate holds a public key, an identity string, principal names, and specific options. OpenSSH certificates use a much simpler format than standard web TLS certificates.

When you sign a key for an agent, you set the identity and list allowed user principals. You can also set a validity window so the credential expires after the task finishes. If you skip the validity setting, the certificate stays valid forever by default. Once the remote host trusts the authority key, it accepts valid certificates without extra key files.

What native SSH setup solves and what keeps the session active

Using signed certificates and scoped host accounts solves the problem of who can log in. You know which agent identity opened the remote shell and when its key expires. You can also restrict which Linux user account the agent assumes on the host.

Still, standard SSH checks stop once the login succeeds and the shell session starts. An SSH key or certificate decides who gets into the server, not what commands run inside. Once the agent has an open shell, it has every permission of that Linux user. A confused agent loop can still delete folders, read secret files, or dump database tables. Standard server logs only show that the key logged in, leaving the exact shell commands unclear.

Ephemeral Credentials + SSH Access Management: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Scoping agent permissions on remote hosts

To reduce risk with native tools, teams create dedicated Linux accounts with narrow file permissions. You should never give an autonomous agent full root permissions on a shared server. Instead, grant the agent user read rights only on the folders it needs to inspect. If the agent must restart a service, scope its system rules to that single service command.

Even with strict user accounts, managing host files across dozens of servers takes constant manual effort. Teams also need a way to inspect commands in flight and mask sensitive output fields. For example, masking can rewrite emails, phone numbers, card numbers, or national IDs in output. Pairing short-lived credentials with command-level checks keeps automated coding sessions safe and auditable.

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 open-source SSH listener on the host where people and agents keep their normal ssh, sftp, and scp tools.

First, hoop.dev guardrails check one-shot commands and file paths before they run. Next, 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

Should I give an OpenHands agent a key with a passphrase?

An autonomous agent cannot type an interactive passphrase unless you preload the key into an agent socket. Most teams load the key into a memory agent on the host before starting the session.

Why use OpenSSH certificates instead of standard public keys for agents?

Standard public keys stay on remote servers until someone removes them by hand. OpenSSH certificates let you set an expiration window and trace actions to a specific key identity.

Can Linux user permissions stop an agent from reading sensitive data?

Linux file permissions can block access to specific files on disk. Still, they cannot rewrite sensitive fields like emails or card numbers inside allowed log files or query results.

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.