How to Configure OpenAI Agents SDK SSH Sandbox

Published
Length
4 min read

Luis Felipe Dias

All posts

You set up an openai agents sdk ssh sandbox by pairing tool functions with restricted Linux accounts. You also sign OpenSSH user certificates that limit what commands the agent can run. Engineering teams often give AI agents a shared SSH key to run remote checks. When that Linux account has broad permissions, a bad prompt can delete files or read secrets. Building a strict sandbox keeps the agent inside a safe boundary on the remote host. How the openai agents sdk ssh sandbox works in practice

SSH Agent Forwarding Security + AI Sandbox Environments: 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 an openai agents sdk ssh sandbox by pairing tool functions with restricted Linux accounts. You also sign OpenSSH user certificates that limit what commands the agent can run. Engineering teams often give AI agents a shared SSH key to run remote checks. When that Linux account has broad permissions, a bad prompt can delete files or read secrets. Building a strict sandbox keeps the agent inside a safe boundary on the remote host.

How the openai agents sdk ssh sandbox works in practice

The agent framework lets a model call Python functions to interact with external systems. To run remote commands, developers wrap an SSH client inside one of these tool functions. The model picks the tool, passes command text, and reads the text output back. The sandbox lives on the target Linux host, not inside the Python agent code. You start by creating a dedicated operating system user with no sudo rights. You place this user in a locked directory so it cannot browse system files. Next, you use the OpenSSH key tool to sign a user certificate with a certificate authority key. An OpenSSH certificate holds a public key, identity text, principal names, and signed options. Certificate checks for users and hosts arrived in OpenSSH version 5.4. This format is much simpler than the X.509 format used in TLS. When you sign the key, you attach an identity name and list the allowed user principals. You also set a short validity window so the signed key expires soon. Without an explicit time window, the signed key stays valid forever. You can also attach certificate options that force a specific command or block port forwarding.

What native SSH sandboxes solve and what they miss

OpenSSH certificates and restricted Linux users solve the initial login problem well. You do not need to copy static public keys to every remote host anymore. The remote server trusts the certificate authority key and checks the principal name at login. If the validity window has passed, the server rejects the login attempt right away. Restricted Linux file permissions also stop the agent from altering system binaries or other user folders. Yet native OS setups only check who logs in at the start of a session. Unless you lock the certificate to one static script, the agent still gets an open shell. Once inside that shell, the model can chain commands or read local app files. Standard SSH logs show that a login happened, but they miss the full command text. If a command prints emails, phone numbers, card numbers, or national IDs, that raw text goes back. The model receives those sensitive values in its prompt context without any filtering. Teams also have no built-in way to pause a single risky command for human approval. Native Linux tools cannot inspect each command in flight or rewrite sensitive output fields.

How to tighten agent tool functions and host rules

You can reduce risk further by changing how you write the agent tool functions. Do not give the model a generic shell tool that accepts raw command strings. Instead, write small Python functions that represent one clear action, like checking disk space. Inside the function, map that request to a fixed script on the remote server. On the remote host, use the certificate option to force that exact script to run. Even if the model sends extra shell text, the server ignores it and runs the script. You should also place the sandboxed host on a separate network segment. Block outbound network traffic from that host so the agent cannot reach other internal servers. Rotate the user certificates before each agent run and give each run a unique identity string. That identity string appears in the server logs and links the session to a specific agent task.

SSH Agent Forwarding Security + AI Sandbox Environments: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

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 use OpenSSH certificates instead of static SSH keys for AI agents?

Static keys stay valid until someone removes them from the remote server. OpenSSH certificates let you set a short time window and attach strict login options. They also embed an identity name that helps teams track which agent started a session.

Can an OpenSSH certificate limit which commands an agent runs?

Yes, you can add a force-command option when you sign the user certificate. The remote server will run only that single command or script when the agent logs in. Still, this approach is hard to manage when an agent needs to run many different diagnostic checks.

What happens if an agent reads sensitive data during an SSH session?

Standard SSH returns all command output straight to the calling Python function. If a log file contains emails, phone numbers, or card numbers, those values enter the model context. You need data masking in the middle to rewrite matched fields in results before the agent reads them.

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.