Agentic SSH

agentic_ssh 🛰️🛡️

别让你的 AI Agent 未经许可就窥探你的 SSH 连接。

为 AI 编码助手（Claude Code、Cursor、Gemini、Antigravity、Copilot、Cline）提供默认安全的 SSH 连接池和 MCP 服务。

agentic_ssh 为你的 AI 助手提供快速、省 Token、异步的 SSH 访问能力，可连接你的家庭实验室、开发服务和集群——并配备严格的零信任主机防护机制，确保它绝不会触碰未授权的基础设施。

📊 Token 与配额影响：原始 SSH 与 agentic_ssh 的对比

指标 / 场景	Agent 提示词中的原始 SSH	使用 agentic_ssh MCP	差异
安全性与影响范围	可完全访问 ~/.ssh/config 中的每台主机	严格的白名单防护（allow_hosts）	阻止访问未授权主机 🛡️
上下文窗口消耗	15,000+ 个 Token（原始 stdout 转储）	185 个 Token（结构化 JSON 遥测数据）	节省 98.8% 的 Token 📉
每次查询的 API 费用	~$0.05 – $0.15	~$0.0004	不到一分钱 💰
连接延迟	重连握手耗时 800ms – 1.5s	0ms（连接池 Keepalive 套接字）	即时响应 ⚡️
长时间运行的构建任务	阻塞 Agent 推理 / 无提示断连	脱离式异步（background: true）	并行工作流 🚀

---

💡 我为什么构建它

我构建 agentic_ssh，是因为我看到自己的 AI 编码 Agent 在我管理的机器集群中执行远程服务排查。

我让它调查一个异常，然后眼睁睁看着它一次又一次打开相同的 SSH 连接，与同一台远程服务通信，每次只检查一件小事。查询多个节点时，它会逐一向每台服务提出完全相同的问题，并且每条命令都会重新执行 TCP/SSH 握手。

更糟的是，每次 docker logs 或系统检查都会把数百甚至数千个 Token 的原始终端噪声和 ANSI 转义码直接倾倒进上下文窗口，几分钟内就耗尽我的 API 预算。每当闲置的 SSH 连接在查询过程中断开，Agent 就会丢失进度，陷入不断重试的循环。

我意识到，可以通过专用的、采用连接池且以安全为先的 MCP 服务，大幅简化这一过程。

---

🛑 为什么给 AI Agent 直接使用原始 SSH 是个糟糕的主意

如果你曾让自主 Agent 直接运行终端命令 ssh，就会让你的机器暴露于巨大风险之中：

• 🚨 不受限制的集群访问（“四处窥探”）：标准 Agent bash 工具可以不受限制地访问你的 ~/.ssh/config。如果你让 Agent 检查本地开发机器，没有任何东西能阻止它查询生产数据库、通过客户端堡垒机跳转，或在不该执行命令的地方运行恶意命令。
• 💥 上下文雪崩：Agent 运行 apt upgrade 或 cargo build，15,000 行编译噪声便会直接倾泻进你的上下文窗口——清空记忆、突破速率限制，还浪费金钱。
• 👻 连接中断导致的无声故障：云 NAT 和 Tailscale 常会在 10 分钟的编译过程中，悄无声息地断开空闲的 SSH 套接字。Agent 会永远卡住，等待永远不会到来的输出。
• 😵‍💫 嵌套转义噩梦：让大模型在 MCP JSON 载荷中的 SSH 字符串里引用 bash 命令（ssh host "bash -c \"echo 'hello'\""），最终总会导致引号出错和语法错误。

---

🪄 agentic_ssh 如何解决这些问题

风险	agentic_ssh 零信任解决方案
未受限制的服务访问	严格的主机白名单（allow_hosts）：如果未配置 allow_hosts，默认会阻止所有主机。你的 Agent 只能访问你明确批准的机器。
上下文窗口膨胀	自动汇总冗长输出，并将大型数据流重定向到隔离的本地会话日志（~/.agentic_ssh/sessions/）。
套接字断开与延迟	基于 Rust 的连接池（russh），支持自动每 30 秒发送保活信号，并可零延迟复用会话。
引号问题	参数会在后台以原生方式进行结构化和转义，让模型彻底摆脱转义烦恼。
长时间任务阻塞	支持 background: true——将长时间构建或迁移任务放入分离线程运行，让 Agent 能继续工作。

---

⚡️ 快速开始（30 秒）

1. 安装

# 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. 自动向你的 AI Agent 注册

只需一条命令，即可检测已安装的 AI 工具并自动注册 MCP 服务：

agentic_ssh install

（支持 Claude Code / Desktop、Cursor、Gemini、Antigravity、Copilot、Zed、Cline 和 Roo-Code。）

3. 验证运行状态

agentic_ssh doctor

---

🤖 提示词示例：AI Agent 能为你做什么

安装完成后，只需用自然语言与 Agent 对话。以下是真实场景中可直接复制粘贴的提示词：

🔍 1. 集群健康状况与资源审计

“检查 stan、cartman 和 aruba 上的 CPU 负载、RAM 使用情况和可用磁盘空间。报告任何瓶颈。”

⚡️ Agent 会在所有 3 个节点上并发调用 get_system_stats，并在 2 秒内为你提供结构化的对比表格。

🛡️ 2. 安全与端口暴露检查

“检查暂存服务上的所有活动 TCP 和 UDP 监听端口。标记任何不该对 0.0.0.0 开放的端口。”

⚡️ Agent 会调用 list_ports，并提供进程归属信息（PID + 二进制文件名），以便立即进行审计。

🐳 3. 容器状态与错误日志跟踪

“检查 cartman 上是否有 Docker 容器崩溃，并跟踪 auth-service 日志的最后 50 行。”

⚡️ Agent 会调用 check_docker_status 和 tail_container_logs，不会让你的上下文窗口被日志淹没。

⏳ 4. 分离式后台任务

“在后台将 stan 上最新的 git 提交部署完成后通知我。”

⚡️ Agent 会以 background: true 运行 run_command，立即释放聊天窗口，并将输出记录在本地会话日志中。

---

🖥️ 面向开发者的 CLI 超能力（内置终端工具）

agentic_ssh 不只是供 AI 使用的 MCP 服务——它还为开发者提供强大的 CLI 工具：

💡 **提示：**在你的 ~/.zshrc 或 ~/.bashrc 中添加 alias ash="agentic_ssh"，减少敲键次数！

agentic_ssh watch：多主机实时流式 TUI

在多个服务器上并发运行命令，通过实时流式窗格查看输出，并在运行结束后检查日志：

# 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：即时多主机脚本编写

直接从终端调用任意内置 MCP 诊断工具，并获取简洁、可解析的 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：实时连接池仪表板

检查活动 SSH 套接字、心跳指标、连接时长和实时运行的命令（含远程 PID/PGID 和超时倒计时），这些信息会内嵌显示在各主机下方：

agentic_ssh tui

---

🧰 内置工具目录

MCP 工具	描述
list_hosts	从 ~/.ssh/config 中发现并返回所有已授权的 SSH 主机别名。
list_groups	返回已定义的多主机服务器组（例如 web-fleet、db-cluster）。
run_command	在多个主机上并发执行命令（支持同步模式或分离式异步后台模式）。
get_system_stats	获取 CPU 负载、RAM 使用率和磁盘分区统计信息。
list_ports	扫描正在监听的 TCP/UDP 套接字，并标明所属进程和 PID。
search_processes	使用正则表达式匹配评估并筛选正在运行的进程。
tail_log	安全地查看标准系统日志文件末尾内容，无需加载数 GB 大小的文件。
tail_container_logs	获取 Docker 容器的实时日志帧。
check_docker_status	返回 Docker 守护进程状态、正在运行的容器和镜像数量。
check_service_status	查询 systemd / systemctl 服务状态。
list_upgradable	列出远程机器上待安装的操作系统软件包更新。
git_pull	安全地获取并更新远程 Git 仓库。
find_large_files	扫描超过指定大小阈值、占用大量磁盘空间的文件。
grep_syslog	在远程 syslog / journalctl 流中搜索特定错误模式。
list_cron_jobs	检查系统和用户的 crontab。
list_network_connections	列出活动网络连接和远程端点。

---

⚙️ 配置（~/.config/agentic_ssh/config.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"]

远程 Shell 要求与超时进程清理

agentic_ssh 会在内存注册表中跟踪每个活动的远程命令，并使用远程进程组 ID（PGID）自动终止超时命令及其派生的子进程。

• POSIX Shell 要求：假定远程目标提供兼容 POSIX 的 sh 或 bash（以及可选的 setsid，用于隔离进程组）。
• 平稳回退：如果目标使用无法检测到 PID 哨兵值的非 POSIX 登录 Shell，agentic_ssh 会记录警告，并尽力关闭通道，而不会导致命令失败。

---

🤝 致谢

• 站在巨人的肩膀上：
  • Russh：高性能纯 Rust SSH 客户端。
  • Ratatui：精美的终端用户界面。
  • Enzo：来自 tokensave 的 MCP 安装器灵感。

---

💖 赞助 Sandbanks

agentic_ssh 是独立、自主的开源软件，由团队构建并维护。

如果 agentic_ssh 为你节省了令牌预算、保障了基础设施安全，或让你的 AI 结对编程工作流更高效：

👉 在 GitHub Sponsors 上赞助 @sandbanks

• 赞助者可获得 GitHub Sponsor 徽章，访问私密的 sandbanks/vip 讨论区和早期 RFC，并享有优先问题分类处理。

---

📄 许可证

采用 MIT 和 Apache 2.0 双重许可。

---

_{MCP 服务标识符：mcp-name: io.github.sandbanks/agentic_ssh}