How to Configure Mastra SSH Credentials

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up mastra ssh credentials by loading private keys or OpenSSH certificates into your runtime. Then your agent tools use those keys to log in to remote hosts and run commands. Most teams start by putting a static private key into a local secret store. This fast setup works at first, but broad host roles create big risks later. If an AI agent gets full shell permissions, one bad prompt can break production servers. How mastra ssh credentials work in agent workflows Mastra is a framework

Ephemeral Credentials + 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 credentials by loading private keys or OpenSSH certificates into your runtime. Then your agent tools use those keys to log in to remote hosts and run commands. Most teams start by putting a static private key into a local secret store. This fast setup works at first, but broad host roles create big risks later. If an AI agent gets full shell permissions, one bad prompt can break production servers.

How mastra ssh credentials work in agent workflows

Mastra is a framework that lets teams build AI agents with custom action tools. When an agent needs to check a server, it calls a shell tool. That tool reads your stored key and opens an SSH session to the target host. Many teams use standard public and private key pairs for this login step. An admin copies the public key to the server and gives the agent the private key.

Some teams use OpenSSH certificates instead of static keys to manage host logins. OpenSSH added certificate support in version 5.4 with a format much simpler than X.509. A certificate Authority key signs a user public key to create the certificate. The signed file holds the public key, an identity string, principal names, and login options. When you sign a key, you set the identity and list the allowed user principals. You can also set a time window so the certificate expires on schedule. Without an expiration window, a signed certificate stays valid forever by default.

What native SSH setup solves and what it leaves open

Using OpenSSH certificates or scoped keys solves the basic host login problem. You can control which Linux user the Mastra agent logs in as on a host. You can also use a jump host to keep your servers off the public internet. Certificates let you stop copying static public keys to every single machine you run.

Still, native SSH setup only decides who logs in at the start of a session. It does not inspect or control what individual shell commands do in flight. Once the agent logs in as a user, it gets every permission that user holds. If the agent runs a destructive command, the Linux host runs it right away. Also, standard SSH logs show that a login happened, not the full output of commands. If a command prints customer emails, phone numbers, card numbers, or national IDs, raw text returns. The AI model receives that sensitive data unless a filter rewrites matched fields in results.

Ephemeral Credentials + SSH Access Management: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Why static agent keys create audit gaps

When multiple Mastra workflows share one SSH key, your server logs lose clear identity details. The host only sees the shared Linux user name on every single connection. Your security team cannot tell which specific agent run or user prompt triggered a command. Rotating that shared key is also hard because you must update every agent store together. If a key leaks in a build log, an attacker can log in from anywhere. Teams need a way to check every command and remove static keys from agent hosts.

Inspect one-shot SSH commands and file tasks

SSH certificates and host rules decide who is allowed on a machine. Setup alone does not check single commands or block sftp reads on sensitive paths. By design, hoop.dev runs an open-source SSH listener on the host where people and agents keep their normal ssh, sftp, and scp tools.

First, hoop.dev guardrails check one-shot commands and file paths before they run. Next, hoop.dev data masking masks matched values in file downloads. The audit trail logs the certificate principal, requested action, and verdict without storing session content. Interactive shells carry no guardrails and can be turned off when every action must be checked. Explore the code on GitHub.

Frequently asked questions

Where should I store SSH keys for Mastra agents?

Store private keys in an encrypted secret manager rather than in source code files. Pass the key into the agent runtime only when the tool needs to run. Better yet, remove static keys from the agent host so secrets cannot leak.

Why are OpenSSH certificates better than static keys for agents?

OpenSSH certificates let you sign a public key with an identity and an expiration time. You do not need to add static public keys to every remote server by hand. Remember to set a validity window when signing, or the certificate stays valid forever.

Can Linux user permissions stop an AI agent from reading sensitive data?

Linux permissions only block access at the file or process level for that user account. If an agent needs log access to fix bugs, it can read everything inside those logs. You need in-flight filtering to rewrite emails, phone numbers, or card numbers in command output.

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.