How to Configure Gemini CLI SSH Credentials

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up gemini cli ssh credentials by loading your keys into the local SSH agent. Then the AI tool uses your local shell to log in to remote hosts. Most teams let the terminal tool use the developer's own key pair. This setup is fast to start, but it gives the AI agent broad host access. If the user key has admin rights, the agent gets those exact same rights. How gemini cli ssh credentials work in practice The command line agent runs tasks inside your local terminal shell. When you ask it

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 gemini cli ssh credentials by loading your keys into the local SSH agent. Then the AI tool uses your local shell to log in to remote hosts. Most teams let the terminal tool use the developer's own key pair. This setup is fast to start, but it gives the AI agent broad host access. If the user key has admin rights, the agent gets those exact same rights.

How gemini cli ssh credentials work in practice

The command line agent runs tasks inside your local terminal shell. When you ask it to check a server, it calls the standard OpenSSH client. The client reads your local config file and looks for a matching private key. If you run an SSH agent in memory, the tool uses that loaded key. The agent does not hold its own separate key store by default. Instead, it inherits whatever login state your shell already has open.

Teams that want tighter control often switch from static keys to OpenSSH certificates. An OpenSSH certificate holds a public key, identity info, principal names, and signed options. A Certificate Authority key signs this bundle to prove the user or host identity. OpenSSH certificates use a much simpler format than standard TLS certificates. You can set a time window on each certificate so access expires on schedule. If you skip the time window during signing, the certificate stays valid forever. You can also bake rules into the certificate to limit what the session allows.

Why native SSH setup leaves a runtime gap

Native OpenSSH keys and certificates do a great job of proving who logs in. They verify that a trusted developer or signed principal started the server session. You can also route traffic through a bastion or jump host for network control. Still, the SSH daemon checks identity only when the session first opens. Once the login succeeds, the remote shell runs every command the principal is allowed.

This creates a major risk when an AI agent drives the terminal session. A human developer might need broad server permissions to fix a broken app. When the AI agent shares that shell, it can run destructive commands by mistake. It can restart services, change system files, or read private logs on the host. Standard SSH keys cannot read the intent of each shell command in flight.

Server logs and command output also create a data exposure problem for teams. When an AI agent runs a command, the remote server sends raw text back. That output might include emails, phone numbers, card numbers, or national IDs. The local CLI tool reads that text and sends it to the model provider. Native SSH tools just move raw bytes through an encrypted pipe. They do not inspect command streams or rewrite 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.

Steps to limit risk with local SSH configs

First, do not let the AI agent use your main admin key pair. Create a separate key pair with a pass-phrase just for automated terminal tasks. On the remote host, link that public key to a low-privilege Linux user. This stops the agent from running root commands if it makes a mistake.

Second, use a Certificate Authority to sign short-lived user certificates for your team. Always set a short time window when signing so keys expire after work hours. Set explicit principal names on the certificate so it only works on test hosts. Even with these steps, remember that OS user rules are coarse. You still need a way to inspect commands and mask sensitive output in flight.

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 inline open-source SSH listener on the host where engineers and AI agents keep their normal ssh, sftp, and scp tools. On every production command or file operation, hoop.dev decides whether to pass, mask, block, or hold it for approval.

First, hoop.dev guardrails check one-shot commands and file paths before they run, and 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 does Gemini CLI store SSH keys?

The tool does not store SSH keys inside its own app folder. It calls your system OpenSSH client, which reads keys from your standard user folder.

Can I use an SSH bastion with an AI terminal agent?

Yes, the agent uses your local SSH config file when it connects to hosts. If you set up a jump host there, the agent routes traffic through it.

Why are static SSH keys risky for AI coding tools?

Static keys never expire on their own and grant full shell permissions. Every command the AI tool generates runs with your full user rights on the server.

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.