Agentic_SSH
agentic_ssh is a high-performance MCP server written in Rust that enables AI agents to orchestrate, monitor, and manage remote machines over SSH in a token-efficient, asynchronous manner.
Host & Group Management
List Hosts: Discover all configured SSH host aliases from
~/.ssh/config.List Groups: View custom multi-host groups for batch/cluster operations.
Remote Command Execution
Run Commands: Execute shell commands on one or multiple hosts simultaneously, with support for background/async execution (returns log path immediately), quiet mode, output abbreviation, and configurable progress intervals.
System Monitoring
System Stats: Retrieve CPU load averages, RAM, and disk utilization from hosts in parallel.
List Ports: Discover active listening TCP/UDP ports with associated processes and PIDs, with optional filtering.
Network Connections: Display active TCP/UDP socket connections.
Service & Docker Status: Check systemd service status and Docker engine/container status.
Process & Log Inspection
Search Processes: Filter running processes on remote hosts using regex patterns, with optional CPU/memory stats.
Tail Log Files: Fetch the last N lines of remote log files or Docker container logs (with optional timestamps).
Wait for Log Pattern: Block and stream logs until a regex pattern is matched or a timeout is reached — useful for verifying deployments or service startups.
Grep Syslog: Search syslog for custom patterns.
Software & Configuration
Package Updates: List upgradable packages on remote hosts.
Git Operations: Perform
git pullon remote repositories.Find Large Files: Identify files exceeding a specified size limit.
List Cron Jobs: View configured cron schedules on remote systems.
Efficiency & Agent Integration
Token-efficient session telemetry, smart progress tickers, hardened connection heartbeats, and zero-quoting headaches for command arguments.
Supports integration with various AI agent frameworks and automated/manual configuration.
Provides tools for interacting with Docker containers on remote hosts, including tailing container logs, checking Docker engine and container status, and waiting for log patterns in container outputs.
Provides a tool to perform git pull operations on remote repositories, enabling automated updates and synchronization of codebases across hosts.
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
Metric / Scenario | Raw SSH in Agent Prompt | With | The Difference |
Security & Blast Radius | Full access to every host in | Strict Whitelist Guardrail ( | 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 ( | 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.
Related MCP server: portal-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 upgradeorcargo 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 |
|
Unchecked Server Access | Strict Host Whitelist ( |
Bloated Context Windows | Automatically summarizes verbose outputs and redirects large streams to isolated local session logs ( |
Dropped Sockets & Lag | Rust-native connection pooling ( |
Broken Quoting | Arguments are structured and escaped natively behind the scenes—zero escaping headaches for the model. |
Blocking Long Tasks | Supports |
⚡️ 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 -- doctor2. 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_statsconcurrently 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_portswith 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_statusandtail_container_logswithout 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_commandwithbackground: 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~/.zshrcor~/.bashrcto 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, connection lifetimes, and live running commands (with remote PID/PGID and timeout countdowns) inline under each host:
agentic_ssh tui🧰 Built-in Tool Catalog
MCP Tool | Description |
| Discovers and returns all authorized SSH host aliases from |
| Returns defined multi-host server groups (e.g., |
| Executes commands concurrently across hosts (supports sync or detached async background mode). |
| Fetches CPU load, RAM utilization, and disk partition stats. |
| Scans active listening TCP/UDP sockets with process & PID attribution. |
| Evaluates and filters running processes with regex matching. |
| Safely tails standard system log files without loading multi-gigabyte files. |
| Fetches real-time log frames from Docker containers. |
| Returns Docker daemon health, running containers, and image counts. |
| Queries |
| Lists pending OS package updates across remote machines. |
| Safely fetches and updates a remote Git repository. |
| Scans for disk-hogging files exceeding a size threshold. |
| Searches remote syslog / journalctl streams for specific error patterns. |
| Inspects system and user crontabs. |
| 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:
# 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"]Remote Shell Requirements & Timeout Process Cleanup
agentic_ssh tracks every active remote command in an in-memory registry and automatically kills timed-out commands (and their spawned child processes) using their remote Process Group ID (PGID).
POSIX Shell Requirement: Remote targets are assumed to provide a POSIX-compliant
shorbash(and optionallysetsidfor isolated process groups).Graceful Fallback: If a target uses a non-POSIX login shell where the PID sentinel cannot be detected,
agentic_sshlogs a warning and falls back to best-effort channel closure without failing the command.
🤝 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/vipdiscussions 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
Available Tools
9 toolsget_system_statsA
Fetch CPU load average, RAM, and disk utilization metrics on a single host ('host') or multiple hosts concurrently ('hosts'). If using 'hosts', returns a JSON map mapping hostnames to their metrics. Prefer 'hosts' to query cluster status in parallel.
Inputs: host, hosts.
list_groupsA
Returns a map of configured remote SSH host groups. The map keys represent group names, and the values are lists of target SSH hosts. Useful to see what multi-host SSH groups are available to query/run/watch.
Inputs: no named parameters.
list_hostsA
Returns the list of configured remote SSH hosts. Useful to see what remote machines are available to target.
Inputs: no named parameters.
list_portsA
Lists active listening TCP/UDP ports, matching processes, and PIDs on a single host ('host') or multiple hosts concurrently ('hosts'). If using 'hosts', returns a JSON map mapping hostnames to their active port list. Optionally filter by 'port'. Prefer 'hosts' to scan service availability across multiple machines simultaneously.
Inputs: host, port, hosts.
run_commandA
Executes a shell command on a single host ('host') or multiple hosts concurrently ('hosts'). If using 'hosts', returns a JSON map mapping hostnames to their stdout, stderr, and exit codes. Features optional 'background' execution (starting the command and returning a local log file path immediately for async tracking), 'quiet' execution (suppressing progress logs), and output abbreviation controls. Prefer 'hosts' to execute commands across cluster nodes simultaneously.
Inputs: command (required), host, hosts, quiet, +5 more.
search_processesA
Searches running processes on a single host ('host') or multiple hosts concurrently ('hosts') matching a regex 'pattern'. If using 'hosts', returns a JSON map mapping hostnames to their matched process list. Optionally returns full user/CPU/mem stats if 'full_info' is true. Prefer 'hosts' to find running services across multiple cluster nodes simultaneously.
Inputs: pattern (required), host, hosts, full_info.
tail_container_logsA
Fetch the last N lines of logs from a remote Docker container on a single host ('host') or multiple hosts concurrently ('hosts'). If using 'hosts', returns a JSON map mapping hostnames to their success status and container log output. Prefer 'hosts' to query container logs across multiple machines simultaneously.
Inputs: container (required), host, hosts, lines, +1 more.
tail_logA
Fetch the last N lines of a remote log file on a single host ('host') or multiple hosts concurrently ('hosts'). If using 'hosts', returns a JSON map mapping hostnames to their log output. Prefer 'hosts' to query logs across multiple machines simultaneously.
Inputs: file_path (required), host, hosts, lines.
wait_for_log_patternA
Blocks and streams a remote log file or Docker container logs on a single host ('host') or multiple hosts concurrently ('hosts') until a regex 'pattern' is matched or a timeout is reached. If using 'hosts', returns a JSON map of hostnames to success/error/timeout statuses containing the matched line. Extremely useful for verifying startup or events across cluster nodes without polling.
Inputs: pattern (required), host, hosts, container, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a clearly distinct operation: host/group discovery, system metrics, ports, process search, arbitrary command execution, log tailing, container log tailing, and pattern-based log waiting. Even the two log-tail tools are separated by source type (file vs container), and wait_for_log_pattern has a distinct blocking behavior.
All tool names follow a consistent snake_case verb-first pattern: list_, get_, run_, search_, tail_, and wait_for_. The verbs are specific and the nouns clearly indicate the target resource, making the naming both predictable and scannable.
Nine tools is a well-scoped set for an SSH operations server. It covers host discovery, monitoring, command execution, process inspection, and log observation without bloating the surface or leaving it feeling thin.
The toolset covers the core SSH workflow: enumerate hosts, inspect system state, run commands, search processes, and monitor logs. The main gap is file transfer or remote file editing, though run_command can work around many of those needs via shell commands.
Maintenance
Related MCP Connectors
End-to-end encrypted messaging and work coordination for autonomous AI agents.
Your AI agent is smart enough to code all day. Local firewall & zero-loss runtime.
AI-native programming language and toolchain for accountable, verifiable agent-driven development.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to establish and manage persistent SSH connections to remote hosts for executing commands. Supports SSH config files, multi-host management, and automatic reconnection with thread-safe concurrent operations.1551 PyPI11MIT
- AlicenseAqualityBmaintenanceSSH orchestration MCP server for coding agents, enabling persistent bash sessions, hash-protected remote file editing, SFTP transfers, SSH tunnels, and multi-host orchestration with connection reuse across tools.148Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to orchestrate a heterogeneous machine fleet via SSH, with unified command execution, file transfer, and dispatch of coding agents across platforms.2Apache 2.0
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to remotely execute shell commands and transfer files on SSH hosts, including jump-host tunneling, background tasks, resumable transfers, and optional approval of destructive commands, while SSH credentials remain in the local process. It runs over stdio or a streamable HTTP daemon and supports auditing, allow/deny lists, and multiple authentication methods.ISC