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.

📊 Token & Quota Impact: Raw SSH vs. agentic_ssh

---

🛑 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

---

⚡️ Quick Start (30 Seconds)

1. Install

# 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:

agentic_ssh install

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

3. Verify Health

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:

# 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:

# 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:

agentic_ssh tui

---

🧰 Built-in Tool Catalog

---

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

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

# 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

• 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.

---

_{MCP Server Identifier: mcp-name: io.github.sandbanks/agentic_ssh}