<!-- mcp-name: io.github.sandbanks/agentic_ssh -->

[![Release](https://github.com/sandbanks/agentic_ssh/actions/workflows/release.yml/badge.svg)](https://github.com/sandbanks/agentic_ssh/actions/workflows/release.yml)
[![Sponsor](https://img.shields.io/badge/Sponsor-sandbanks-ea4aaa?style=flat-square&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/sandbanks)
[![MCP Toplist](https://mcptoplist.com/badge/io.github.sandbanks%2Fagentic_ssh.svg)](https://mcptoplist.com/server/io.github.sandbanks%2Fagentic_ssh)
[![agentic_ssh MCP server](https://glama.ai/mcp/servers/sandbanks/agentic_ssh/badges/score.svg)](https://glama.ai/mcp/servers/sandbanks/agentic_ssh)
[![Crates.io](https://img.shields.io/crates/v/agentic_ssh.svg)](https://crates.io/crates/agentic_ssh)
[![Homebrew](https://img.shields.io/badge/brew-sandbanks%2Ftap-orange?logo=homebrew)](https://github.com/sandbanks/agentic_ssh#quick-start)

# `agentic_ssh` 🛰️🛡️

> **Stop your AI agent from nosing around your SSH connections without permission.**
> 
> A secure-by-default SSH connection pool & MCP server for AI coding assistants (Claude Code, Cursor, Gemini, Antigravity, Copilot, Cline).

`agentic_ssh` gives your AI assistant fast, token-efficient, and asynchronous SSH access to your homelab, dev servers, and clusters—**with strict zero-trust host guardrails so it can never touch unauthorized infrastructure.**

![AI Agent Multi-Host Interrogation & Security Guardrail](https://assets.sandbanks.tech/agentic_ssh/agentic_ssh_hero.gif)

### 📊 Token & Quota Impact: Raw SSH vs. `agentic_ssh`

| Metric / Scenario | Raw SSH in Agent Prompt | With `agentic_ssh` MCP | The Difference |
| :--- | :--- | :--- | :--- |
| **Security & Blast Radius** | Full access to every host in `~/.ssh/config` | **Strict Whitelist Guardrail** (`allow_hosts`) | Unauthorized hosts blocked 🛡️ |
| **Context Window Consumption** | 15,000+ tokens (raw stdout dump) | **185 tokens** (structured JSON telemetry) | **98.8% token savings** 📉 |
| **API Cost per Query** | ~$0.05 – $0.15 | **~$0.0004** | Fraction of a cent 💰 |
| **Connection Latency** | 800ms – 1.5s reconnect handshake | **0ms** (pooled Keepalive socket) | Instant response ⚡️ |
| **Long-Running Builds** | Blocks agent reasoning / silent dropout | **Detached async** (`background: true`) | Parallel workflows 🚀 |

---

## 💡 Why I Built This

I built `agentic_ssh` after watching my AI coding agent do remote server triage across my own fleet of machines.

I asked it to investigate an anomaly. I sat there watching as it opened the same SSH connection time after time to talk to the same remote server, checking one small thing at a time. When querying multiple nodes, it would ask the exact same question of each server individually, running fresh TCP/SSH handshakes for every single command.

Worse, every single `docker logs` or system check dumped hundreds—sometimes thousands—of tokens of raw terminal noise and ANSI escape codes straight into the context window, chewing through my API budget in minutes. And whenever an idle SSH connection dropped mid-query, the agent would lose its place and spin in retry loops.

I realised that could be dramatically streamlined with a dedicated, connection-pooled, security-first MCP server.

---

## 🛑 Why Giving AI Agents Raw SSH Is a Bad Idea

If you've ever let an autonomous agent run raw terminal `ssh`, you're exposing your machines to huge risks:

* 🚨 **Unrestricted Fleet Access ("Nosing Around")**: Standard agent bash tools have full, unchecked access to your `~/.ssh/config`. If you ask an agent to inspect a local dev box, **nothing stops it from querying your production database, jumping through client bastions, or running rogue commands where it shouldn't.**
* 💥 **The Context Avalanche**: The agent runs `apt upgrade` or `cargo build`, and **15,000 lines of compiler noise** dump straight into your context window—wiping out memory, blowing up rate limits, and wasting money.
* 👻 **Silent Death by Dropout**: Cloud NATs and Tailscale love to silently drop idle SSH sockets during a 10-minute compile. The agent hangs forever waiting for output that will never arrive.
* 😵‍💫 **Nested Escaping Hell**: Asking an LLM to quote bash inside an SSH string inside an MCP JSON payload (`ssh host "bash -c \"echo 'hello'\""`) invariably leads to broken quotes and syntax errors.

---

## 🪄 How `agentic_ssh` Fixes This

| The Danger | `agentic_ssh` Zero-Trust Solution |
| :--- | :--- |
| **Unchecked Server Access** | **Strict Host Whitelist (`allow_hosts`)**: If `allow_hosts` is not configured, **all hosts are blocked by default**. Your agent can only touch machines you have explicitly approved. |
| **Bloated Context Windows** | Automatically summarizes verbose outputs and redirects large streams to isolated local session logs (`~/.agentic_ssh/sessions/`). |
| **Dropped Sockets & Lag** | Rust-native connection pooling (`russh`) with automatic 30s keepalives and zero-latency session reuse. |
| **Broken Quoting** | Arguments are structured and escaped natively behind the scenes—zero escaping headaches for the model. |
| **Blocking Long Tasks** | Supports `background: true`—fires long builds or migrations into detached threads so the agent can keep working. |

---

## ⚡️ Quick Start (30 Seconds)

### 1. Install

```bash
# macOS & Linux (Homebrew)
brew install sandbanks/tap/agentic_ssh

# Or with cargo-binstall (pre-compiled binary)
cargo binstall agentic_ssh

# Or run instantly with Nix (zero compile)
nix run github:sandbanks/agentic_ssh -- doctor
```

### 2. Auto-Register with Your AI Agents

One command detects your installed AI tools and registers the MCP server automatically:

```bash
agentic_ssh install
```

*(Supports **Claude Code / Desktop**, **Cursor**, **Gemini**, **Antigravity**, **Copilot**, **Zed**, **Cline**, and **Roo-Code**).*

### 3. Verify Health

```bash
agentic_ssh doctor
```

---

## 🤖 Prompt Recipes: What Your AI Agent Can Do

Once installed, just talk to your agent naturally. Here are real-world prompts you can copy & paste:

### 🔍 1. Cluster Health & Resource Audit
> *"Check the CPU load, RAM usage, and available disk space across stan, cartman, and aruba. Report any bottlenecks."*
> 
> ⚡️ *Agent calls `get_system_stats` concurrently across all 3 nodes and gives you a structured comparison table in 2 seconds.*

### 🛡️ 2. Security & Port Exposure Check
> *"Inspect all active listening TCP and UDP ports on our staging server. Flag anything open on 0.0.0.0 that shouldn't be."*
> 
> ⚡️ *Agent calls `list_ports` with process attribution (PID + binary name) for instant auditing.*

### 🐳 3. Container Status & Error Log Tailing
> *"Check if any Docker containers crashed on cartman, and tail the last 50 lines of the auth-service logs."*
> 
> ⚡️ *Agent calls `check_docker_status` and `tail_container_logs` without flooding your context window.*

### ⏳ 4. Detached Background Jobs
> *"Deploy the latest git commit on stan in the background and notify me when it finishes."*
> 
> ⚡️ *Agent runs `run_command` with `background: true`, frees up your chat immediately, and tracks the output in a local session log.*

---

## 🖥️ CLI Superpowers for Humans (Built-in Terminal Tools)

`agentic_ssh` isn't just an MCP server for AI—it includes powerful CLI tools for human developers too:

> 💡 **Tip:** Add `alias ash="agentic_ssh"` to your `~/.zshrc` or `~/.bashrc` to save keystrokes!

### `agentic_ssh watch`: Multi-Host Live Streaming TUI
Watch commands run concurrently across multiple servers with live streaming panes and post-run log inspection:

![Multi-Host Command Watcher TUI](https://assets.sandbanks.tech/agentic_ssh/agentic_ssh_watch.gif)

```bash
# Watch a command on multiple hosts concurrently
agentic_ssh watch stan,cartman,aruba "pnpm --version"

# Watch an entire host group defined in your config
agentic_ssh watch web-fleet "docker compose ps"
```

### `agentic_ssh json`: Instant Multi-Host Scripting
Call any built-in MCP diagnostic tool directly from your terminal and get clean, parseable JSON:

```bash
# Get structured system stats across hosts
agentic_ssh json get_system_stats stan,cartman

# Query listening ports
agentic_ssh json list_ports '{"hosts": ["stan", "aruba"]}'
```

### `agentic_ssh tui`: Live Connection Pool Dashboard
Inspect active SSH sockets, heartbeat metrics, and connection lifetimes:

```bash
agentic_ssh tui
```

---

## 🧰 Built-in Tool Catalog

| MCP Tool | Description |
| :--- | :--- |
| `list_hosts` | Discovers and returns all authorized SSH host aliases from `~/.ssh/config`. |
| `list_groups` | Returns defined multi-host server groups (e.g., `web-fleet`, `db-cluster`). |
| `run_command` | Executes commands concurrently across hosts (supports sync or detached async background mode). |
| `get_system_stats` | Fetches CPU load, RAM utilization, and disk partition stats. |
| `list_ports` | Scans active listening TCP/UDP sockets with process & PID attribution. |
| `search_processes` | Evaluates and filters running processes with regex matching. |
| `tail_log` | Safely tails standard system log files without loading multi-gigabyte files. |
| `tail_container_logs` | Fetches real-time log frames from Docker containers. |
| `check_docker_status` | Returns Docker daemon health, running containers, and image counts. |
| `check_service_status` | Queries `systemd` / `systemctl` service states. |
| `list_upgradable` | Lists pending OS package updates across remote machines. |
| `git_pull` | Safely fetches and updates a remote Git repository. |
| `find_large_files` | Scans for disk-hogging files exceeding a size threshold. |
| `grep_syslog` | Searches remote syslog / journalctl streams for specific error patterns. |
| `list_cron_jobs` | Inspects system and user crontabs. |
| `list_network_connections` | Lists active network connections and remote endpoints. |

---

## ⚙️ Configuration (`~/.config/agentic_ssh/config.toml`)

You can define host groups and security boundaries in an optional configuration file:

```toml
# Security boundaries: Only allow safe hosts
allow_hosts = ["stan", "cartman", "kyle", "*.local"]
ignore_hosts = ["prod-db-primary", "secure-vault"]

# Multi-host groups for easy targeting
[groups]
fleet = ["stan", "cartman", "aruba", "kyle"]
pis = ["stan", "cartman", "kyle"]
web = ["aruba", "stan"]

# Custom parameterized agent tools
[tools.deploy_stack]
description = "Pulls latest compose repo and updates stack containers."
command = ["docker", "compose", "-f", "/opt/app/docker-compose.yml", "up", "-d"]
allow_hosts = ["stan", "cartman"]
```

---

## 🤝 Acknowledgments

* Standing on the shoulders of giants:
  * **Russh**: High-performance pure Rust SSH client.
  * **Ratatui**: Gorgeous terminal user interfaces.
  * **Enzo**: MCP installer inspiration from `tokensave`.

---

## 💖 Sponsoring Sandbanks

`agentic_ssh` is built and maintained as independent, sovereign open-source software.

If `agentic_ssh` saves your token budget, secures your infrastructure, or makes your AI pair-programming workflow faster:

👉 **[Sponsor @sandbanks on GitHub Sponsors](https://github.com/sponsors/sandbanks)**

* Sponsoring unlocks the **GitHub Sponsor badge**, access to the private **`sandbanks/vip`** discussions and early RFCs, and priority issue triage.

---

## 📄 License

Dual-licensed under MIT and Apache 2.0.

---

<sub>MCP Server Identifier: `mcp-name: io.github.sandbanks/agentic_ssh`</sub>