How to Configure OpenHands SSH Sandbox
You set up an openhands ssh sandbox by linking the agent to an isolated container over SSH. You create a dedicated user role and give the agent a key to log in. Engineering teams often use this setup to keep AI code tasks away from the host machine. Still, broad shell roles still let an agent run risky commands inside that box. If the box holds database keys or cloud tokens, the agent can read and use them. How the openhands ssh sandbox architecture works OpenHands runs AI agents that write c
SSH Access Management + AI Sandbox Environments: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up an openhands ssh sandbox by linking the agent to an isolated container over SSH. You create a dedicated user role and give the agent a key to log in. Engineering teams often use this setup to keep AI code tasks away from the host machine. Still, broad shell roles still let an agent run risky commands inside that box. If the box holds database keys or cloud tokens, the agent can read and use them.
How the openhands ssh sandbox architecture works
OpenHands runs AI agents that write code, run tests, and fix bugs on their own. Instead of running tasks on a local machine, the platform can use a remote shell. The control node starts a session by logging into a separate container or virtual machine. Once inside, the agent uses standard shell tools to read files and run scripts.
To lock down the login step, teams often move away from static keys. OpenSSH 5.4 added certificate support for both users and hosts. This format is much simpler than the X.509 format used in TLS. A Certification Authority key signs a public key to make a user or host certificate. Each certificate holds a public key, an identity string, principal names, and a set of options.
Using signed certificates helps teams manage how the agent logs into the sandbox. The admin signs the agent key with the CA key and sets the allowed principal names. The target container checks the CA signature instead of keeping a long list of public keys. When the validity window ends, the agent can no longer log in with that certificate.
What native SSH setup solves and what it misses
An SSH sandbox keeps file changes and broken packages inside a disposable machine. If the AI agent deletes a system folder, the host server stays safe. Using OpenSSH certificates also stops static private keys from sitting on disk forever. You know which identity logged into the box and when the session started.
Still, native SSH setup only checks who can log into the machine. Once the shell session starts, OpenSSH does not inspect the commands the agent runs next. An agent inside the sandbox needs network paths and credentials to do useful work. It might query a test database, call an internal API, or pull private code.
SSH Access Management + AI Sandbox Environments: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
If you put database passwords or API tokens inside the sandbox, the agent can read them. A bad prompt or a logic loop can cause the agent to drop tables. It could also pull customer rows that hold emails, phone numbers, or card numbers. Standard SSH controls cannot mask those fields in query results or block a single bad command.
Securing agent actions beyond the shell login
To run AI agents safely, teams must separate the execution box from target credentials. The sandbox should only give the agent a place to compile code and run local tests. It should never store raw secrets for databases, cloud accounts, or internal services.
Teams also need visibility into every action the agent takes during a task. Knowing that an agent opened an SSH session at noon is not enough for an audit. Security teams need a clear log of every shell command and database query that ran. When sensitive data returns from a query, masking rules should rewrite matched fields like national IDs.
Add command and file guardrails to SSH access
Host firewalls and certificate principals control who opens an SSH session. Yet an allowed user or agent can still run a bad one-shot command or pull sensitive files over sftp. In practice, hoop.dev provides an open-source SSH server with guardrails on the host that uses OpenSSH certificates.
Using hoop.dev SSH controls, guardrails check one-shot commands, env variable names, and sftp or scp paths before they run. Port forwards default to deny unless the target is listed. Because interactive shells have no statement boundary and carry no guardrails, teams can turn them off so every command is checked and logged. Check out the MIT-licensed project on GitHub.
Frequently asked questions
Why use an SSH sandbox for OpenHands instead of a local folder?
A remote sandbox separates the AI agent from your host operating system and local files. If the agent runs a bad script, the damage stays inside the disposable container.
How do OpenSSH certificates improve sandbox login security?
A Certification Authority key signs the agent key with an identity and principal names. The sandbox trusts the CA key, so you do not manage static keys on each host.
Does an SSH sandbox stop an AI agent from leaking database data?
No, the sandbox only isolates the operating system where the agent runs its shell commands. If the sandbox holds database credentials, the agent can still query tables and read raw rows.
Related guides
In this post