How to Configure Mastra SSH Permissions
You set up mastra ssh permissions by mapping agent tools to scoped Linux accounts. You also use signed OpenSSH certificates with strict time limits for every host login. Many teams start by giving their AI agents a shared private key. That key often maps to a broad user role on the remote server. When permissions are too wide, one bad prompt can delete files or leak secrets. A tight setup limits both how the agent logs in and what it runs. How native mastra ssh permissions work Mastra runs as
SSH Access Management + AI Agent Permissions: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up mastra ssh permissions by mapping agent tools to scoped Linux accounts. You also use signed OpenSSH certificates with strict time limits for every host login. Many teams start by giving their AI agents a shared private key. That key often maps to a broad user role on the remote server. When permissions are too wide, one bad prompt can delete files or leak secrets. A tight setup limits both how the agent logs in and what it runs.
How native mastra ssh permissions work
Mastra runs as a TypeScript framework where agents call custom tools to do work. When an agent needs to check a server, it calls a shell tool. That tool opens an SSH session to the target host using local keys. Mastra does not have its own built-in Linux user manager. Instead, your mastra ssh permissions rely on the underlying OpenSSH setup on your hosts.
To lock this down, teams create a separate Linux user just for the agent. They remove root rights from this user and limit folder read rules. Instead of static keys, teams can use an OpenSSH Certification Authority key. The key generation tool signs a public key to make a user certificate. This certificate holds a public key, an identity string, and valid user names. It also holds a set of options signed by the authority key. OpenSSH certificates use a much simpler format than standard TLS certificates. You can set a short time window when you sign the user certificate. If you do not set a window, the certificate stays valid forever.
What native SSH setups solve and where they fall short
Native OpenSSH user rules and signed certificates solve the initial login problem well. They check who can log in to a host and when that right expires. You can route traffic through a bastion or jump host to centralize network paths. You can also bind a key to a single Linux account on the server. This stops an agent from logging into hosts it has no business touching.
Still, host login checks leave a big gap during live agent runs. Once the SSH session starts, the host trusts every command that user can run. An AI agent does not always run the exact same shell script twice. It builds commands on the fly based on user prompts and system outputs. Native host rules decide who logs in, not what individual commands do in flight.
If an agent has read rights to a log file, it reads everything inside. Those logs might hold customer emails, phone numbers, card numbers, or national IDs. Standard SSH returns the raw text straight back to the agent context. Only masking rewrites matched fields in results before the agent processes the text. Also, standard Linux sudo rules are all-or-nothing for a given binary or script. You cannot pause a single risky command mid-session and ask a human for approval.
SSH Access Management + AI Agent Permissions: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Steps to tighten agent shell tools
Start by splitting your agent tools into small, single-purpose tasks. Do not give a Mastra agent a raw shell tool that takes arbitrary strings. Build narrow tools that only take safe values like a service name. Pass those values into fixed scripts that live on the remote server.
Next, drop static keys from the machine that runs your Mastra app. Sign short-lived OpenSSH user certificates right before the agent starts its task. Set the principal name on the certificate to match a restricted Linux role. Turn off port forwarding and agent forwarding in the certificate options. Keep the Linux user out of admin groups so it cannot change system files.
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
How do I stop a Mastra agent from running root commands over SSH?
Map the agent key to a basic Linux user with no sudo rights. Grant that user read rights only to the exact folders it needs to check.
Why use OpenSSH certificates instead of static SSH keys for agents?
Static keys stay valid until someone removes them from the remote host file. Signed OpenSSH certificates let you set an expiration time so access ends on schedule.
Can native SSH permissions hide sensitive data in command outputs?
No, OpenSSH only handles the encrypted tunnel and the initial user login check. It sends back raw command output, including emails, phone numbers, and card numbers.
Related guides
In this post