How to Configure OpenAI Agents SDK SSH Least Privilege

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up openai agents sdk ssh least privilege by giving agents restricted host accounts. You also pair those accounts with short-lived certificates and strict command rules. Many teams start by giving an AI agent a broad admin key. This choice lets the agent run any command across your servers. A bad prompt or model mistake can then delete files or leak secrets. Scoping down what the agent can run prevents these wide outages. How openai agents sdk ssh least privilege works in practice The

Least Privilege Principle + SSH Agent Forwarding Security: 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 openai agents sdk ssh least privilege by giving agents restricted host accounts. You also pair those accounts with short-lived certificates and strict command rules. Many teams start by giving an AI agent a broad admin key. This choice lets the agent run any command across your servers. A bad prompt or model mistake can then delete files or leak secrets. Scoping down what the agent can run prevents these wide outages.

How openai agents sdk ssh least privilege works in practice

The OpenAI Agents SDK lets models call local tools and functions to finish tasks. When an agent needs to check a server, it calls a tool that opens an SSH session. The remote server checks the key or certificate before it runs any command. OpenSSH supports signed user certificates that hold a public key and identity data. A certificate authority key signs these files and sets valid user principals. Certificate checks for users and hosts arrived in OpenSSH 5.4.

To keep rights small, you create a dedicated Linux user just for the agent. You strip write rights from this user across all system folders. You also use OpenSSH certificate options to lock the session down further. For example, you can set a validity window so the key expires fast. Without a validity window, an OpenSSH certificate stays valid forever by default. You can also bind the certificate to a single script on the target host. When the agent connects, the server runs only that preset script and nothing else.

What native SSH controls solve and what they miss

Native OpenSSH settings do a great job of locking down initial login checks. User certificates stop teams from leaving static public keys on every single host. Dedicated Linux users stop an agent from reading root files or changing system configs. Forced commands make sure a key only triggers one specific check or status script. These steps cut down the blast radius if an agent key leaks.

Still, host-level setups only decide who logs in and which base script starts. They do not inspect the live text or arguments an agent sends in flight. If an agent needs to run varied diagnostic commands, static forced commands break down. Teams often fall back to a general shell so the agent can work. Once the agent has a shell, native SSH cannot block a bad command mid-session. It also cannot mask sensitive text like emails or card numbers in command output. When a server prints user phone numbers or national IDs, that raw text goes straight to the model. Standard host logs also struggle to tie a shell command back to a specific agent run.

Least Privilege Principle + SSH Agent Forwarding Security: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Separating agent tool calls from raw host keys

A safer pattern keeps raw SSH private keys off the machine running the agent. Instead of giving the SDK a local key file, you wrap each task in a tight tool function. Each tool takes typed inputs rather than a raw shell string. A service outside the agent checks those inputs against a strict allowlist. If an agent asks to read a log, the runner checks the file path first. It rejects any path that points to system secrets or private user folders.

You should also filter the text that comes back from the remote server. Log files often hold emails, phone numbers, or credit card numbers from customer requests. Filtering this output rewrites matched fields in results before the agent reads the text. This step keeps private data out of third-party model prompts and trace logs. Finally, require a human to approve any write or restart task before it runs. Read-only checks can run right away, while state changes pause for a quick review.

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 AI agents not use shared admin SSH keys?

Shared admin keys let an agent run any command on the target server. If the model misreads a prompt, it can drop files or stop vital services. A shared key also makes it hard to see which agent ran a command.

How do OpenSSH certificates help with agent access?

OpenSSH certificates let a central authority sign a user key with a short expiry time. You do not need to copy static keys to every server ahead of time. When the time window ends, the agent cannot log in with that certificate again.

Can Linux user permissions alone stop data leaks to the model?

No, Linux permissions only control which files the agent user can open and read. If an allowed app log holds emails or card numbers, the OS prints them. You need output filtering to rewrite matched fields in results before the model processes 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.