Agentic SSH

agentic_ssh 🛰️🛡️

許可なくSSH接続を詮索するAIエージェントを阻止しましょう。

AIコーディングアシスタント（Claude Code、Cursor、Gemini、Antigravity、Copilot、Cline）向けの、デフォルトでセキュアなSSH接続プール兼MCPサーバーです。

agentic_ssh を使うと、ホームラボ、開発サーバー、クラスターへ、AIアシスタントから高速でトークン効率に優れた非同期SSHアクセスが可能になります。厳格なゼロトラストのホストガードレールにより、許可されていないインフラストラクチャにアクセスすることは決してありません。

📊 トークンとクォータへの影響：生のSSHと agentic_ssh の比較

指標／シナリオ	エージェントのプロンプトで生のSSHを使用	agentic_ssh MCPを使用	違い
セキュリティと影響範囲	~/.ssh/config 内のすべてのホストへの完全なアクセス	厳格なホワイトリストによるガードレール（allow_hosts）	許可されていないホストをブロック 🛡️
コンテキストウィンドウの消費量	15,000トークン以上（生の標準出力のダンプ）	185トークン（構造化されたJSONテレメトリ）	トークンを98.8％節約 📉
クエリあたりのAPIコスト	約$0.05～$0.15	約$0.0004	1セント未満 💰
接続レイテンシ	再接続時のハンドシェイクに800ms～1.5s	0ms（接続プール内のKeepaliveソケット）	即座に応答 ⚡️
長時間実行ビルド	エージェントの推論をブロック／応答が途絶える	切り離された非同期処理（background: true）	ワークフローを並行実行 🚀

---

💡 これを作った理由

自分のマシン群でAIコーディングエージェントがリモートサーバーのトリアージを行う様子を見て、agentic_ssh を作りました。

異常を調査するよう依頼したところ、同じリモートサーバーに何度もSSH接続し、毎回ひとつずつ小さな項目を確認しているのを目の当たりにしました。複数のノードを調べるときは、各サーバーに同じ質問を個別に投げかけ、コマンドごとに新しいTCP／SSHハンドシェイクを実行していました。

さらに悪いことに、docker logs やシステムチェックのたびに、生のターミナル出力やANSIエスケープコードが数百、時には数千ものトークンとしてコンテキストウィンドウにそのまま流れ込み、数分でAPI利用枠を使い切っていました。アイドル状態のSSH接続がクエリの途中で切れると、エージェントは作業の続きが分からなくなり、再試行を繰り返していました。

接続プールを備え、セキュリティを最優先にした専用のMCPサーバーを使えば、こうした問題を大幅に改善できると気づきました。

---

🛑 AI エージェントに生の SSH を使わせるのが危険な理由

自律型エージェントに生のターミナル ssh を実行させたことがあるなら、マシンを大きなリスクにさらしています。

• 🚨 フリートへの無制限アクセス（「あちこちを探る」）：標準的なエージェントの bash ツールは、~/.ssh/config に無制限でアクセスできます。ローカルの開発マシンを調べるようエージェントに頼んでも、本番データベースを問い合わせたり、クライアントの踏み台サーバーを経由したり、実行すべきでない場所で不正なコマンドを実行したりするのを止めるものはありません。
• 💥 コンテキストの大洪水：エージェントが apt upgrade や cargo build を実行すると、15,000 行ものコンパイラー出力がそのままコンテキストウィンドウに流れ込み、メモリを使い果たし、レート制限に達しやすくなり、コストも無駄にかかります。
• 👻 切断による静かな停止：クラウド NAT や Tailscale は、10 分間のコンパイル中にアイドル状態の SSH ソケットをひそかに切断することがあります。エージェントは、二度と届かない出力を待ち続け、永久に停止します。
• 😵‍💫 多重エスケープ地獄：SSH 文字列内の bash を MCP JSON ペイロード内で引用するよう LLM に頼むと（ssh host "bash -c \"echo 'hello'\""）、決まって引用符が壊れ、構文エラーになります。

---

🪄 agentic_ssh がこれを解決する方法

危険	agentic_ssh のゼロトラストソリューション
未検証のサーバーアクセス	厳格なホスト許可リスト（allow_hosts）：allow_hosts が設定されていない場合、デフォルトですべてのホストがブロックされます。エージェントがアクセスできるのは、明示的に許可したマシンだけです。
肥大化したコンテキストウィンドウ	冗長な出力を自動的に要約し、大きなストリームは分離されたローカルのセッションログ（~/.agentic_ssh/sessions/）にリダイレクトします。
ソケット切断と遅延	Rust ネイティブの接続プーリング（russh）を採用し、30 秒ごとの自動キープアライブと、遅延のないセッション再利用を実現します。
引用符の破損	引数は内部でネイティブに構造化され、エスケープされるため、モデルがエスケープに悩まされることはありません。
長時間タスクによるブロック	background: true に対応しており、長時間のビルドやマイグレーションをデタッチされたスレッドで実行するため、エージェントは作業を続けられます。

---

⚡️ クイックスタート（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 エージェントに自動登録

1 つのコマンドでインストール済みの AI ツールを検出し、MCP サーバーを自動登録します。

agentic_ssh install

（Claude Code / Desktop、Cursor、Gemini、Antigravity、Copilot、Zed、Cline、Roo-Code に対応しています。）

3. ヘルス状態の確認

agentic_ssh doctor

---

🤖 プロンプトの例：AI エージェントにできること

インストール後は、エージェントに自然な言葉で話しかけるだけです。コピー＆ペーストして使える、実際の利用を想定したプロンプトを紹介します。

🔍 1. クラスターのヘルス状態とリソースの監査

「stan、cartman、aruba 全体の CPU 負荷、RAM 使用量、利用可能なディスク容量を確認してください。ボトルネックがあれば報告してください。」

⚡️ エージェントは 3 台すべてのノードで同時に get_system_stats を呼び出し、2 秒で比較表にまとめて報告します。

🛡️ 2. セキュリティとポート公開状況の確認

「ステージングサーバーで、現在リッスン中の TCP ポートと UDP ポートをすべて調べてください。公開すべきでない 0.0.0.0 上のポートにフラグを立ててください。」

⚡️ エージェントはプロセス情報（PID とバイナリ名）付きで list_ports を呼び出し、すぐに監査できるようにします。

🐳 3. コンテナーの状態とエラーログの追跡

「cartman でクラッシュした Docker コンテナーがないか確認し、auth-service のログの最後の 50 行を表示してください。」

⚡️ エージェントはコンテキストウィンドウをあふれさせることなく、check_docker_status と tail_container_logs を呼び出します。

⏳ 4. バックグラウンドでのデタッチ実行ジョブ

「stan に最新の git コミットをバックグラウンドでデプロイし、完了したら通知してください。」

⚡️ エージェントは 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	プロセスと PID の情報を含め、アクティブな TCP/UDP 待ち受けソケットをスキャンします。
search_processes	正規表現による照合で、実行中のプロセスを評価して絞り込みます。
tail_log	数 GB のファイルを読み込まずに、標準的なシステムログファイルの末尾を安全に表示します。
tail_container_logs	Docker コンテナからリアルタイムのログフレームを取得します。
check_docker_status	Docker デーモンの健全性、実行中のコンテナ、イメージ数を返します。
check_service_status	systemd / systemctl サービスの状態を照会します。
list_upgradable	リモートマシン全体で保留中の OS パッケージ更新を一覧表示します。
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"]

リモートシェル要件とタイムアウト時のプロセスのクリーンアップ

agentic_ssh はアクティブなリモートコマンドをすべてメモリ内のレジストリで追跡し、リモートのプロセスグループ ID（PGID）を使って、タイムアウトしたコマンドとその子プロセスを自動的に強制終了します。

• POSIX シェル要件：リモートターゲットは、POSIX 準拠の sh または bash（および分離されたプロセスグループを利用する場合は、任意で setsid）を提供するものとします。
• グレースフルフォールバック：ターゲットが非 POSIX のログインシェルを使用しており、PID センチネルを検出できない場合、agentic_ssh は警告をログに記録し、コマンドを失敗させることなく、可能な範囲でチャネルを閉じます。

---

🤝 謝辞

• 偉大な先人たちの成果の上に成り立っています：
  • Russh：高性能な純 Rust 製 SSH クライアント。
  • Ratatui：美しいターミナルユーザーインターフェース。
  • Enzo：tokensave から着想を得た MCP インストーラー。

---

💖 Sandbanks を支援する

agentic_ssh は、独立した自律的なオープンソースソフトウェアとして開発・保守されています。

agentic_ssh によってトークンの使用量を節約できる、インフラストラクチャを安全に保護できる、または AI ペアプログラミングのワークフローを高速化できる場合は：

👉 GitHub Sponsors で @sandbanks をスポンサーする

• スポンサーになると、GitHub スポンサーバッジ、非公開の sandbanks/vip ディスカッションと RFC の先行公開へのアクセス、優先的な Issue のトリアージを利用できます。

---

📄 ライセンス

MIT と Apache 2.0 のデュアルライセンスです。

---

_{MCP サーバー識別子：mcp-name: io.github.sandbanks/agentic_ssh}