How to Configure Amazon Q SSH Credentials
You set up amazon q ssh credentials by loading keys into your local SSH agent. Then Amazon Q uses your local shell to log in to remote hosts. Most teams start by pointing the assistant at standard private keys on a laptop. This works fast for testing. Still, broad host permissions let an AI assistant run risky commands on live servers. How amazon q ssh credentials work in practice Amazon Q does not keep its own secret store for remote server logins. Instead, the coding agent runs commands ins
Ephemeral Credentials + SSH Access Management: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up amazon q ssh credentials by loading keys into your local SSH agent. Then Amazon Q uses your local shell to log in to remote hosts. Most teams start by pointing the assistant at standard private keys on a laptop. This works fast for testing. Still, broad host permissions let an AI assistant run risky commands on live servers.
How amazon q ssh credentials work in practice
Amazon Q does not keep its own secret store for remote server logins. Instead, the coding agent runs commands inside your local shell environment. When the agent needs to reach a remote Linux server, it calls the local SSH client. That client reads your local config files and talks to your running SSH agent.
You can use standard public and private key pairs for this setup. A better choice is to use OpenSSH certificates. In OpenSSH, a certificate authority key signs a user public key to make a certificate. Each certificate holds a public key, identity info, principal names, and a set of options. OpenSSH certificates use a much simpler format than X.509 certificates. Certificate login for users and hosts arrived in OpenSSH 5.4.
To set this up, an admin signs your user key with a certificate authority key. The admin sets a key identity and lists the allowed user principals. The remote host trusts the certificate authority key instead of tracking individual public keys. When Amazon Q runs a remote command, OpenSSH checks the signed certificate and opens the session.
Why local keys and certificates are not enough for AI agents
OpenSSH certificates solve key distribution, yet they leave a big gap during active sessions. A certificate decides who can log in to a host and which user account they get. Once the session starts, the SSH server hands control to the remote shell. It does not check each command that the AI agent sends down the wire.
Another risk comes from how local keys sit on a developer machine. If a key sits unlocked in your local agent, any local process can use it. When you allow Amazon Q to run shell commands, it shares those exact same rights. A bad prompt or a simple mistake can drop files or change system state. The remote Linux user often has broad sudo rights for admin work.
Ephemeral Credentials + SSH Access Management: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Static keys also stay valid until someone removes them from the remote server. Even with OpenSSH certificates, the default validity window lasts forever unless an admin sets a limit. If a developer leaves a long-lived certificate on disk, the AI agent can use it anytime. Native SSH logs also show that a user logged in, not what the AI agent ran.
Steps to reduce risk when AI agents use SSH
Teams should separate human admin keys from the credentials that AI tools can reach. Start by creating a restricted Linux user on the remote host with read-only permissions. Do not give this account sudo rights or write permissions on system folders. Sign an OpenSSH user certificate that only lists this restricted principal name.
Next, always set a short expiration window when signing the user certificate. Store the key in a separate SSH agent socket that only runs during active tasks. Close the socket as soon as the debugging task finishes. Even with these steps, native SSH still lacks per-command checks and field masking for output.
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
Does Amazon Q store SSH private keys in the cloud?
No, the local agent uses the SSH client and keys on your own workstation. Your private keys stay on your machine while the agent runs local shell commands.
Can I use OpenSSH certificates with Amazon Q?
Yes, because the agent uses your standard system SSH client for remote commands. Any OpenSSH certificate loaded into your local SSH agent works for those sessions.
Why is sharing my main SSH agent with an AI assistant risky?
Your main SSH agent often holds keys with root or sudo rights on production hosts. An AI tool using that agent can run destructive commands without a second check.
Related guides
In this post