How to Configure OpenHands SSH Least Privilege
You set up openhands ssh least privilege by giving the AI agent a restricted Linux user account. You also sign its public key with an OpenSSH certificate authority to set strict options. Many teams start by giving an AI coding agent a standard user key with root power. That approach lets the agent run any command on the remote machine. If the agent makes a bad plan, it can delete files or expose secrets. How openhands ssh least privilege works OpenHands is an AI coding agent that runs shell c
Least Privilege Principle + SSH Access Management: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up openhands ssh least privilege by giving the AI agent a restricted Linux user account. You also sign its public key with an OpenSSH certificate authority to set strict options. Many teams start by giving an AI coding agent a standard user key with root power. That approach lets the agent run any command on the remote machine. If the agent makes a bad plan, it can delete files or expose secrets.
How openhands ssh least privilege works
OpenHands is an AI coding agent that runs shell commands to fix bugs and write code. When the agent works on a remote host, it connects over SSH like a human user. To limit its power, you must restrict both the SSH session and the local Linux user.
Start by creating a dedicated Linux user on the target host just for the agent. Give this user read and write permissions only on the project folder it needs to change. Do not put this user in the admin group or allow it to run root commands.
Next, replace static public keys with OpenSSH user certificates. In OpenSSH, a certificate authority key signs a user public key to create a certificate. This certificate holds a public key, an identity name, valid user names, and a set of options. OpenSSH certificates use a much simpler format than TLS certificates. You can set a short time window when you sign the agent certificate. When the window ends, the agent can no longer log in with that key.
Setting command limits on the remote host
After you set up the user and certificate, you can limit what the SSH session allows. OpenSSH lets you embed options inside the signed certificate or within the server authorized keys file. For example, you can turn off port forwarding, agent forwarding, and user terminal allocation. Blocking port forwarding stops the agent from opening network tunnels to other internal machines.
You can also attach a forced command to the certificate. When the agent logs in, the SSH server ignores the requested shell command. Instead, the server runs only the script or wrapper you defined in advance. A wrapper script can check the command the agent sent against a small list of safe tools. If the agent tries to run a blocked tool, the script stops the request right away.
Least Privilege Principle + SSH Access Management: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What native SSH setup solves and where it falls short
Using a scoped Linux user and OpenSSH certificates solves the initial login problem. You know which agent logged in, and its key expires on a set schedule. The agent cannot escalate to root or open network tunnels to your other servers.
Still, native SSH setup mostly decides who can log in to the machine. Once a shell session starts, SSH does not inspect individual commands or output in flight. Writing and maintaining custom wrapper scripts for every new project takes a lot of team time. If a script has a small flaw, the agent can bypass it and run destructive commands. Native SSH also does not rewrite sensitive data like emails or phone numbers in command output. If the agent reads a file with customer card numbers, those values go straight into its prompt.
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 should I use OpenSSH certificates instead of static SSH keys for OpenHands?
Static SSH keys never expire on their own and remain valid until someone deletes them. OpenSSH certificates let you set a time window and embed user principals and session options.
Can a Linux user restriction stop OpenHands from reading sensitive data?
Linux file permissions only control which files the agent user can open on disk. If the agent needs a log file for work, native SSH will not mask emails or national IDs inside it.
What happens if OpenHands gets full sudo rights over SSH?
Full root power lets the AI agent change system settings, install packages, and read any file. A wrong command from the model can break the host or leak secrets stored on disk.
Related guides
In this post