How to Configure OpenHands SSH Connect

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up openhands ssh connect by giving the agent a valid key pair. Then the agent logs in to a remote server to run shell commands. Most teams mount a local key file into the agent container at startup. This quick setup works for early tests on a single dev box. Yet broad host roles let an autonomous agent change files across the whole server. If a prompt goes wrong, the agent has full power over that machine. How openhands ssh connect works with keys and certificates An AI coding agent n

SSH Access Management + End-to-End Encryption: 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 connect by giving the agent a valid key pair. Then the agent logs in to a remote server to run shell commands. Most teams mount a local key file into the agent container at startup. This quick setup works for early tests on a single dev box. Yet broad host roles let an autonomous agent change files across the whole server. If a prompt goes wrong, the agent has full power over that machine.

How openhands ssh connect works with keys and certificates

An AI coding agent needs a shell to read code and run tests. When the agent runs on a remote host, it uses the standard SSH protocol. The client sends a public key to the remote server during login. The server checks if that key sits in the user key file. If the key matches, the server opens a shell session for the agent.

Managing static keys across many hosts gets hard for a growing team. Keys sit on disks and never expire on their own. To fix this, teams can use OpenSSH certificates instead of raw keys. OpenSSH added certificate support for users and hosts in version 5.4. A certificate authority key signs a public key to make a valid certificate. This file holds the public key, an identity string, and allowed principal names. It also holds a set of options signed by the authority key. The OpenSSH format is much simpler than the X.509 format used in TLS.

Instead of copying keys to every host, the server trusts the authority key. When the agent starts an openhands ssh connect session, it presents the signed certificate. The server checks the signature and lets the agent log in right away. Admins can set a validity window when they sign the user certificate. If they skip this step, the certificate stays valid forever by default.

How to scope host roles for AI agents

Before you let an agent log in, create a dedicated Linux user account. Do not let the agent share a root account or a personal user account. Give this new account read and write rules only for the project folder. This step keeps the agent away from system files and other apps.

Next, route the agent traffic through your own jump host or bastion. A bastion gives your team a single network entry point to watch. You can also add certificate options when you sign the agent key. These options can restrict which shell commands the user account can run. When you combine short validity windows with strict principals, you reduce the risk of stolen keys.

SSH Access Management + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native SSH setup solves and what it misses

Native OpenSSH keys and certificates solve the problem of who can log in. They verify the identity of the agent before a shell session begins. A short certificate lifetime also stops old keys from working the next day. Dedicated Linux users keep the agent inside its own home directory.

Still, host login checks stop working once the shell session opens. The server checks the key at the door, not the commands in flight. An agent with an active shell can still run a bad script. It can read sensitive app files or dump local database tables. If a table holds phone numbers, emails, or card numbers, the output shows them. Native SSH does not rewrite matched fields in results before the agent reads them. It also lacks a step for a human to approve a single risky command. Once the agent logs in, every command runs at the speed of the model.

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

How does OpenHands log in to a remote server over SSH?

The agent uses a standard SSH client inside its runtime container. It presents a private key or a signed OpenSSH certificate to the remote host. Once the host checks the key, the agent gets an active shell session.

Why should teams use OpenSSH certificates instead of static keys for agents?

Static keys never expire unless someone removes them from the host file. OpenSSH certificates let admins sign a key with a strict validity window and specific principal names. When the time window ends, the agent can no longer log in.

Can SSH keys stop an AI agent from reading sensitive data?

No, SSH keys and certificates only check identity at login time. Once the shell opens, the agent can run any command allowed for that Linux user. Host login rules do not inspect command output or mask national IDs and emails.

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.