{
  "markdown": "<!-- mcp-name: io.github.sandbanks/agentic_ssh -->\n\n[![Release](https://github.com/sandbanks/agentic_ssh/actions/workflows/release.yml/badge.svg)](https://github.com/sandbanks/agentic_ssh/actions/workflows/release.yml)\n[![Sponsor](https://img.shields.io/badge/Sponsor-sandbanks-ea4aaa?style=flat-square&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/sandbanks)\n[![MCP Toplist](https://mcptoplist.com/badge/io.github.sandbanks%2Fagentic_ssh.svg)](https://mcptoplist.com/server/io.github.sandbanks%2Fagentic_ssh)\n[![agentic_ssh MCP server](https://glama.ai/mcp/servers/sandbanks/agentic_ssh/badges/score.svg)](https://glama.ai/mcp/servers/sandbanks/agentic_ssh)\n[![Crates.io](https://img.shields.io/crates/v/agentic_ssh.svg)](https://crates.io/crates/agentic_ssh)\n[![Homebrew](https://img.shields.io/badge/brew-sandbanks%2Ftap-orange?logo=homebrew)](https://github.com/sandbanks/agentic_ssh#quick-start)\n\n# `agentic_ssh` 🛰️🛡️\n\n> **Stop your AI agent from nosing around your SSH connections without permission.**\n> \n> A secure-by-default SSH connection pool & MCP server for AI coding assistants (Claude Code, Cursor, Gemini, Antigravity, Copilot, Cline).\n\n`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.**\n\n![AI Agent Multi-Host Interrogation & Security Guardrail](https://assets.sandbanks.tech/agentic_ssh/agentic_ssh_hero.gif)\n\n### 📊 Token & Quota Impact: Raw SSH vs. `agentic_ssh`\n\n| Metric / Scenario | Raw SSH in Agent Prompt | With `agentic_ssh` MCP | The Difference |\n| :--- | :--- | :--- | :--- |\n| **Security & Blast Radius** | Full access to every host in `~/.ssh/config` | **Strict Whitelist Guardrail** (`allow_hosts`) | Unauthorized hosts blocked 🛡️ |\n| **Context Window Consumption** | 15,000+ tokens (raw stdout dump) | **185 tokens** (structured JSON telemetry) | **98.8% token savings** 📉 |\n| **API Cost per Query** | ~$0.05 – $0.15 | **~$0.0004** | Fraction of a cent 💰 |\n| **Connection Latency** | 800ms – 1.5s reconnect handshake | **0ms** (pooled Keepalive socket) | Instant response ⚡️ |\n| **Long-Running Builds** | Blocks agent reasoning / silent dropout | **Detached async** (`background: true`) | Parallel workflows 🚀 |\n\n---\n\n## 🛑 Why Giving AI Agents Raw SSH Is a Bad Idea\n\nIf you've ever let an autonomous agent run raw terminal `ssh`, you're exposing your machines to huge risks:\n\n* 🚨 **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.**\n* 💥 **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.\n* 👻 **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.\n* 😵‍💫 **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.\n\n---\n\n## 🪄 How `agentic_ssh` Fixes This\n\n| The Danger | `agentic_ssh` Zero-Trust Solution |\n| :--- | :--- |\n| **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. |\n| **Bloated Context Windows** | Automatically summarizes verbose outputs and redirects large streams to isolated local session logs (`~/.agentic_ssh/sessions/`). |\n| **Dropped Sockets & Lag** | Rust-native connection pooling (`russh`) with automatic 30s keepalives and zero-latency session reuse. |\n| **Broken Quoting** | Arguments are structured and escaped natively behind the scenes—zero escaping headaches for the model. |\n| **Blocking Long Tasks** | Supports `background: true`—fires long builds or migrations into detached threads so the agent can keep working. |\n\n---\n\n## ⚡️ Quick Start (30 Seconds)\n\n### 1. Install\n\n```bash\n# macOS & Linux (Homebrew)\nbrew install sandbanks/tap/agentic_ssh\n\n# Or with cargo-binstall (pre-compiled binary)\ncargo binstall agentic_ssh\n\n# Or run instantly with Nix (zero compile)\nnix run github:sandbanks/agentic_ssh -- doctor\n```\n\n### 2. Auto-Register with Your AI Agents\n\nOne command detects your installed AI tools and registers the MCP server automatically:\n\n```bash\nagentic_ssh install\n```\n\n*(Supports **Claude Code / Desktop**, **Cursor**, **Gemini**, **Antigravity**, **Copilot**, **Zed**, **Cline**, and **Roo-Code**).*\n\n### 3. Verify Health\n\n```bash\nagentic_ssh doctor\n```\n\n---\n\n## 🤖 Prompt Recipes: What Your AI Agent Can Do\n\nOnce installed, just talk to your agent naturally. Here are real-world prompts you can copy & paste:\n\n### 🔍 1. Cluster Health & Resource Audit\n> *\"Check the CPU load, RAM usage, and available disk space across stan, cartman, and aruba. Report any bottlenecks.\"*\n> \n> ⚡️ *Agent calls `get_system_stats` concurrently across all 3 nodes and gives you a structured comparison table in 2 seconds.*\n\n### 🛡️ 2. Security & Port Exposure Check\n> *\"Inspect all active listening TCP and UDP ports on our staging server. Flag anything open on 0.0.0.0 that shouldn't be.\"*\n> \n> ⚡️ *Agent calls `list_ports` with process attribution (PID + binary name) for instant auditing.*\n\n### 🐳 3. Container Status & Error Log Tailing\n> *\"Check if any Docker containers crashed on cartman, and tail the last 50 lines of the auth-service logs.\"*\n> \n> ⚡️ *Agent calls `check_docker_status` and `tail_container_logs` without flooding your context window.*\n\n### ⏳ 4. Detached Background Jobs\n> *\"Deploy the latest git commit on stan in the background and notify me when it finishes.\"*\n> \n> ⚡️ *Agent runs `run_command` with `background: true`, frees up your chat immediately, and tracks the output in a local session log.*\n\n---\n\n## 🖥️ CLI Superpowers for Humans (Built-in Terminal Tools)\n\n`agentic_ssh` isn't just an MCP server for AI—it includes powerful CLI tools for human developers too:\n\n> 💡 **Tip:** Add `alias ash=\"agentic_ssh\"` to your `~/.zshrc` or `~/.bashrc` to save keystrokes!\n\n### `agentic_ssh watch`: Multi-Host Live Streaming TUI\nWatch commands run concurrently across multiple servers with live streaming panes and post-run log inspection:\n\n![Multi-Host Command Watcher TUI](https://assets.sandbanks.tech/agentic_ssh/agentic_ssh_watch.gif)\n\n```bash\n# Watch a command on multiple hosts concurrently\nagentic_ssh watch stan,cartman,aruba \"pnpm --version\"\n\n# Watch an entire host group defined in your config\nagentic_ssh watch web-fleet \"docker compose ps\"\n```\n\n### `agentic_ssh json`: Instant Multi-Host Scripting\nCall any built-in MCP diagnostic tool directly from your terminal and get clean, parseable JSON:\n\n```bash\n# Get structured system stats across hosts\nagentic_ssh json get_system_stats stan,cartman\n\n# Query listening ports\nagentic_ssh json list_ports '{\"hosts\": [\"stan\", \"aruba\"]}'\n```\n\n### `agentic_ssh tui`: Live Connection Pool Dashboard\nInspect active SSH sockets, heartbeat metrics, and connection lifetimes:\n\n```bash\nagentic_ssh tui\n```\n\n---\n\n## 🧰 Built-in Tool Catalog\n\n| MCP Tool | Description |\n| :--- | :--- |\n| `list_hosts` | Discovers and returns all authorized SSH host aliases from `~/.ssh/config`. |\n| `list_groups` | Returns defined multi-host server groups (e.g., `web-fleet`, `db-cluster`). |\n| `run_command` | Executes commands concurrently across hosts (supports sync or detached async background mode). |\n| `get_system_stats` | Fetches CPU load, RAM utilization, and disk partition stats. |\n| `list_ports` | Scans active listening TCP/UDP sockets with process & PID attribution. |\n| `search_processes` | Evaluates and filters running processes with regex matching. |\n| `tail_log` | Safely tails standard system log files without loading multi-gigabyte files. |\n| `tail_container_logs` | Fetches real-time log frames from Docker containers. |\n| `check_docker_status` | Returns Docker daemon health, running containers, and image counts. |\n| `check_service_status` | Queries `systemd` / `systemctl` service states. |\n| `list_upgradable` | Lists pending OS package updates across remote machines. |\n| `git_pull` | Safely fetches and updates a remote Git repository. |\n| `find_large_files` | Scans for disk-hogging files exceeding a size threshold. |\n| `grep_syslog` | Searches remote syslog / journalctl streams for specific error patterns. |\n| `list_cron_jobs` | Inspects system and user crontabs. |\n| `list_network_connections` | Lists active network connections and remote endpoints. |\n\n---\n\n## ⚙️ Configuration (`~/.config/agentic_ssh/config.toml`)\n\nYou can define host groups and security boundaries in an optional configuration file:\n\n```toml\n# Security boundaries: Only allow safe hosts\nallow_hosts = [\"stan\", \"cartman\", \"kyle\", \"*.local\"]\nignore_hosts = [\"prod-db-primary\", \"secure-vault\"]\n\n# Multi-host groups for easy targeting\n[groups]\nfleet = [\"stan\", \"cartman\", \"aruba\", \"kyle\"]\npis = [\"stan\", \"cartman\", \"kyle\"]\nweb = [\"aruba\", \"stan\"]\n\n# Custom parameterized agent tools\n[tools.deploy_stack]\ndescription = \"Pulls latest compose repo and updates stack containers.\"\ncommand = [\"docker\", \"compose\", \"-f\", \"/opt/app/docker-compose.yml\", \"up\", \"-d\"]\nallow_hosts = [\"stan\", \"cartman\"]\n```\n\n---\n\n## 🤝 Acknowledgments\n\n* Standing on the shoulders of giants:\n  * **Russh**: High-performance pure Rust SSH client.\n  * **Ratatui**: Gorgeous terminal user interfaces.\n  * **Enzo**: MCP installer inspiration from `tokensave`.\n\n---\n\n## 💖 Sponsoring Sandbanks\n\n`agentic_ssh` is built and maintained as independent, sovereign open-source software.\n\nIf `agentic_ssh` saves your token budget, secures your infrastructure, or makes your AI pair-programming workflow faster:\n\n👉 **[Sponsor @sandbanks on GitHub Sponsors](https://github.com/sponsors/sandbanks)**\n\n* Sponsoring unlocks the **GitHub Sponsor badge**, access to the private **`sandbanks/vip`** discussions and early RFCs, and priority issue triage.\n\n---\n\n## 📄 License\n\nDual-licensed under MIT and Apache 2.0.\n\n---\n\n<sub>MCP Server Identifier: `mcp-name: io.github.sandbanks/agentic_ssh`</sub>\n\n",
  "bytes": 10520,
  "sha": "df980a4a9ba0dc4eadfd5e1afd3272d7ba59cc1cb418fc9502b6ac80248d0bfa",
  "repo_slug": "sandbanks/agentic_ssh",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sandbanks_agentic_ssh_d95d6c50/readme"
}