How to Configure Mastra SSH Approval

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up mastra ssh approval by pausing agent workflows before a Linux shell tool runs. A human reviewer then checks the planned command and clicks approve or reject. Engineering teams often give AI agents a static SSH key to run server tasks. If that key has broad Linux permissions, one bad prompt can break a live host. Adding a review step stops risky shell commands before the agent sends them. How mastra ssh approval works in an agent workflow Mastra lets developers build AI agents that

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.

You set up mastra ssh approval by pausing agent workflows before a Linux shell tool runs. A human reviewer then checks the planned command and clicks approve or reject. Engineering teams often give AI agents a static SSH key to run server tasks. If that key has broad Linux permissions, one bad prompt can break a live host. Adding a review step stops risky shell commands before the agent sends them.

How mastra ssh approval works in an agent workflow

Mastra lets developers build AI agents that call external tools and run multi-step workflows. When an agent needs to check a server, it picks an SSH tool call. Without a review gate, the agent opens a connection and runs the shell command right away. To add human review, you split the tool execution into two workflow steps.

First, the agent creates the exact shell string it wants to run on the host. The workflow engine pauses at that step and saves the current state. Next, the app sends an alert to an engineer in Slack or a web dashboard. The alert shows the target host, the Linux user, and the planned command. An engineer reads the request and decides if the action is safe. Once the engineer approves the request, the workflow resumes and runs the SSH command.

How OpenSSH certificates handle server login

While the agent framework manages the workflow pause, OpenSSH manages the server login itself. Many teams replace static keys with OpenSSH certificates, which arrived in OpenSSH 5.4. A Certification Authority key signs a user public key to make a certificate. That certificate holds the public key, an identity string, principal names, and login options. OpenSSH uses a much simpler certificate format than X.509.

Signing a key requires a CA key, an key identity, and one or more principals. You can also set a validity window so the certificate expires after a short time. If you do not set a time window, the certificate stays valid forever. Certificates prove who can log in to a host during that time window.

Where native agent gates and SSH keys fall short

App-level workflow gates and OpenSSH certificates solve different parts of the access problem. OpenSSH certificates check who logs in to the server at the start of a session. Once the session starts, the OS user role decides every action the agent can take. If the agent logs in as root, it can run any command on the box.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Workflow pauses inside the agent app also leave security gaps. The agent app still holds the private SSH key or certificate in its own memory. If a bug or code change skips the pause step, the agent still has full server access. Also, terminal output from the server flows straight back into the agent context. That output often contains raw user emails, phone numbers, card numbers, or national IDs. Native SSH tools do not rewrite those sensitive fields in the results before the model reads them.

Moving command review and data safety outside the agent

A safer design separates the AI agent from the raw server credentials and host keys. Instead of holding keys inside the agent app, you enforce reviews at the network edge. Every command goes through an external check before it reaches the target Linux host. This setup ensures the agent never holds a raw SSH key in its own memory. It also lets teams apply data masking that rewrites matched fields in results in real time.

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

Can Mastra pause a workflow before running a shell command?

Yes, Mastra workflows can pause before a step runs and wait for an external signal. A human reviewer inspects the planned command payload and sends an approval event to resume execution.

Do OpenSSH certificates restrict every command in a session?

An OpenSSH certificate can include an option that forces a single preset command at login. Still, standard certificate logins allow any command that the target Linux user account can run.

How do teams protect sensitive data in SSH command output?

Native SSH returns raw text straight from the remote shell to the calling client. Teams add a data masking step to rewrite emails, phone numbers, and card numbers in 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.