agent-ssh ssh access for agents, without leaking the secret

brokered ssh for developers and ai agents

Give agents server access without giving them credentials.

agent-ssh lets developers expose remote SSH actions to any AI agent through one broker. The broker holds the real access details, whether the server uses certificates or legacy password compatibility, while the agent gets a named target, an approved command surface, and the full response back.

install see the flow

Works with any AI agent that can call a CLI or broker wrapper.

broker://prod-web-1 
$ agent-ssh exec --server staging-api --profile logs \
  --arg service=api \
  --arg "since=5 min ago"

Apr 12 10:00:01 staging systemd[1]: Started api.service.
Apr 12 10:00:02 staging api[1234]: listening on :8080

exit=0

what it does

A safe handoff between your infra and the agent.

Define friendly server aliases and approved profiles once. Agents call the broker instead of raw ssh.

Return stdout, stderr, and exit code so the agent can actually reason about the result.

Keep certificate details, private keys, and password references out of the agent. The broker owns the sensitive path.

Reuse one broker-held SSH connection for multi-step work when unrestricted sessions are explicitly allowed.

how it works

Four moves from config to action.

01

Define the surface

Map aliases, auth mode, and allowed profiles in agent-ssh.toml.

[servers.prod-web-1]
host = "10.0.10.21"
user = "deploy"
allowed_profiles = ["logs", "disk"]
02

Discover what the agent can use

Validate config, list hosts, and list profiles before running anything risky.

agent-ssh config validate
agent-ssh hosts list
agent-ssh profiles list --server prod-web-1
03

Prefer approved commands

Default execution is profile-based, auditable, and easy to repeat.

agent-ssh exec --server prod-web-1 --profile disk
04

Open raw command mode only when needed

Use unrestricted sessions for multi-step investigation, then close them.

agent-ssh session open --server prod-web-1 --mode unrestricted --approval CAB-1234
agent-ssh session exec --session <id> --cmd "uname -a"
agent-ssh session close <id>

install

MacBook and Linux are native. Windows runs through WSL2.

MacBook

macOS is a native path. Homebrew is the simplest setup on both Apple Silicon and Intel MacBooks. 

brew tap aibunny/agent-ssh https://github.com/aibunny/agent-ssh
brew install agent-ssh
agent-ssh --version

agent-ssh init
agent-ssh config validate

Linux

Use Homebrew on Linux, the release installer, Cargo, or the Debian package.

brew tap aibunny/agent-ssh https://github.com/aibunny/agent-ssh
brew install agent-ssh

curl -fsSL https://raw.githubusercontent.com/aibunny/agent-ssh/main/scripts/install.sh | sh

cargo install --git https://github.com/aibunny/agent-ssh agent-ssh-cli

Windows

The current release path is Windows Terminal + WSL2 + Ubuntu or Debian. Native Windows binaries are not shipped by this repo today. 

wsl --install -d Ubuntu
wsl
curl -fsSL https://raw.githubusercontent.com/aibunny/agent-ssh/main/scripts/install.sh | sh
agent-ssh --version

agent compatibility

Use the CLI anywhere. Use the skill where Codex is available.

The tool itself is agent-agnostic. If an AI agent can run a CLI command or call a wrapper around agent-ssh, it can use the brokered flow.

This repo now also includes a reusable Codex skill at skills/agent-ssh so Codex agents automatically prefer profiles, respect approval gates, avoid secret leakage, and clean up unrestricted sessions.

skill highlights

validate config

list aliases and profiles

prefer profile execution

use raw mode deliberately

never expose credentials

security model

The agent gets access to actions, not access to secrets.

The secure default is certificate-oriented. For older systems, legacy_password exists as a compatibility lane, but the password stays behind the broker as an opaque secret reference.

  • exact server aliases
  • profile allowlists
  • approval references for protected runs
  • audit events for every broker decision
  • explicit opt-in for unrestricted sessions
[servers.prod-web-1]
host = "10.0.10.21"
user = "deploy"
requires_approval = true
allow_unrestricted_sessions = true

[servers.legacy-web]
auth_method = "legacy_password"
password_secret_ref_env_var = "AGENT_SSH_LEGACY_WEB_PASSWORD_REF"