How to Configure Pydantic AI SSH Approval

Published
Length
3 min read

Luis Felipe Dias

All posts

To set up pydantic ai ssh approval, wrap your shell tool in a review step. This step pauses the agent until a human approves the command and key. Teams often connect agents to Linux hosts using shared keys or broad sudo rules. When an agent holds broad rights, one bad prompt can wipe files or expose data. How native pydantic ai ssh approval works In a standard setup, an AI agent needs a tool to run remote commands. Developers build a Python function that opens an SSH session to a target host.

Approval Chains & Escalation + 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.

To set up pydantic ai ssh approval, wrap your shell tool in a review step. This step pauses the agent until a human approves the command and key. Teams often connect agents to Linux hosts using shared keys or broad sudo rules. When an agent holds broad rights, one bad prompt can wipe files or expose data.

How native pydantic ai ssh approval works

In a standard setup, an AI agent needs a tool to run remote commands. Developers build a Python function that opens an SSH session to a target host. Pydantic AI checks the input types before the agent calls this tool. To add an approval step, the function must pause before sending the command.

The app sends the planned command to a chat channel or ticket queue. A human reviewer reads the text and clicks approve or deny. Once approved, the app needs a way to log in to the host. Many teams use OpenSSH certificates instead of static keys for this step.

A Certificate Authority key signs a user public key to create an OpenSSH certificate. This certificate holds a public key, identity info, principal names, and signed options. OpenSSH certificates use a much simpler format than X.509 certificates. When the reviewer approves the request, the system signs a certificate for the agent.

The certificate includes a validity window so the login rights expire after a set time. If the team skips the validity rule, the certificate stays valid forever by default. The agent then uses this signed certificate to log in through a jump host. Finally, the remote server checks the principal name and runs the shell command.

What native setups solve and what they miss

Combining tool validation with OpenSSH certificates solves several basic login problems. You do not have to copy static public keys to every remote server. The Certificate Authority signs the key only when the agent needs to work. Type checks in the agent code also stop broken strings from reaching the shell.

Still, this native flow leaves a major gap during the live session. OpenSSH certificates decide who can log in to a host, not what happens next. Once the agent opens a shell session, the host trusts that user principal. If an approved script spawns a subshell, the certificate cannot inspect those new commands.

Approval Chains & Escalation + SSH Access Management: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

App-level review checks the tool arguments before the network call starts. It does not watch the actual traffic flowing over the SSH protocol. If the agent reads a file with customer emails or card numbers, raw data returns. The native SSH connection will pass those phone numbers and national IDs right back.

Keeping track of what the agent did is also hard with native tools alone. Server logs show that a principal logged in, not which prompt triggered the command. Teams end up stitching together app logs and host logs after an incident happens. You need a way to govern individual commands and mask data in flight.

Managing keys and command scope for AI agents

When teams build their own approval logic, they must maintain that custom code across apps. Every new agent needs the same chat hooks, state checks, and key signing scripts. If a developer forgets to add the wrapper to one tool, the agent bypasses review.

Also, local agents often keep the signed key file on disk during the task. Any other process running in the same container can read that key and log in. Moving approval and session control out of the agent code fixes these design flaws. The agent simply sends a request, and the network layer handles the rest.

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 should AI agents not use static SSH keys?

Static keys never expire on their own and often sit in plain text files. If an agent leaks its key in a log, anyone can log in to your servers. Signed OpenSSH certificates let you set a short validity window for each task.

Does Pydantic AI block dangerous shell commands by default?

No, Pydantic AI validates data schemas and types for tool inputs and outputs. It makes sure the input matches your Python model, such as a string or integer. It does not know if a valid string will delete a folder on your host.

How does data masking work for SSH command output?

Native OpenSSH returns all standard output directly to the client without checking the text. To hide sensitive fields, an inline system must inspect the output stream before the agent reads it. Masking rewrites matched fields like emails, card numbers, or phone numbers in the results.

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.