How to Configure Pydantic AI SSH Sandbox

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a pydantic ai ssh sandbox by pairing typed tool calls with scoped Linux hosts. Your agent sends checked inputs to a locked host over an OpenSSH user certificate. Many teams start by giving an AI agent a broad SSH key on a shared server. That wide key lets one bad prompt change files, read secrets, or break running services. A safe setup pairs strict input schemas with tight Linux user permissions and short login windows. How a pydantic ai ssh sandbox works Pydantic AI lets your tea

AI Sandbox Environments + SSH Access Management: 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 a pydantic ai ssh sandbox by pairing typed tool calls with scoped Linux hosts. Your agent sends checked inputs to a locked host over an OpenSSH user certificate. Many teams start by giving an AI agent a broad SSH key on a shared server. That wide key lets one bad prompt change files, read secrets, or break running services. A safe setup pairs strict input schemas with tight Linux user permissions and short login windows.

How a pydantic ai ssh sandbox works

Pydantic AI lets your team build agents that use strict data schemas for every tool call. Instead of letting the model write raw shell strings, you define typed fields for each action. The agent fills in those fields, and your app checks them before opening an SSH session. If the model gives the wrong data type, the check fails before any remote call runs.

On the remote host, you lock down how that tool call logs in with OpenSSH certificates. An OpenSSH certificate holds a public key, identity data, principal names, and options signed by a CA. OpenSSH certificates use a much simpler format than X.509 certificates and arrived in OpenSSH 5.4. Your CA key signs the agent public key and sets a key identity and principal list. You also set a short validity window when signing, since the default window lasts forever.

Next, you place the remote Linux user inside an isolated sandbox on the target machine. You restrict the Linux account to a small folder tree and strip away sudo rights. When the agent tool runs, it logs in as that locked principal and runs one task. Once the task finishes, the tool closes the session and returns structured text to the model.

What native SSH controls solve and where gaps remain

Native OpenSSH certificates and schema checks solve the first layer of agent safety. Typed schemas stop the model from passing broken fields into your Python function. OpenSSH certificates stop you from leaving static public keys on every sandbox host. When a certificate expires, the agent can no longer log in to the host.

Still, host login checks only decide who gets in, not what happens inside the session. Once a session starts, standard SSH treats every command from that Linux user the same way. If a tool permits shell strings or file reads, the agent can still pull sensitive data. A script output might return customer emails, phone numbers, card numbers, or national IDs to the model. Native SSH does not rewrite matched fields in results before they reach the agent context.

AI Sandbox Environments + SSH Access Management: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Tightening command scope and data handling for agents

To lower risk, break one general SSH tool into many small, single-purpose tools. Create one tool to read service status and another tool to check disk space. Map each tool to its own certificate principal or restricted command rule on the host. This stops the agent from chaining arbitrary shell steps together during a bad run.

You also need a clear audit trail for every command the agent runs on a host. Standard Linux logs show that a user logged in, but they often miss full command output. Teams also need a way to pause risky actions until a human approves the command. Scrubbing emails and card numbers from stdout keeps sensitive records out of your model provider logs.

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 avoid giving an AI agent a raw bash tool over SSH?

A raw bash tool lets the model run any command the Linux user can run. Prompt injection or model errors can delete files, read secrets, or harm the host. Typed tool inputs limit the agent to fixed actions that your code checks first.

How do OpenSSH certificates help secure an agent sandbox?

A CA key signs the agent key with a fixed identity, principal list, and time window. You do not have to copy static public keys to every remote host by hand. When the validity window ends, the certificate stops working without manual cleanup on the host.

How can I protect sensitive data in SSH output from reaching the LLM?

Linux permissions only block whole files and cannot filter specific lines inside command output. You need output filtering that finds emails, phone numbers, or card numbers in flight. Masking rewrites matched fields in results before the text returns to the agent.

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.