maestro/ui/src/content/help/14-ssh.md

id, title, category, order, keywords

id	title	category	order	keywords
ssh	SSH リモート操作	advanced	140	SSH リモート exec アップロード コンソール PTY デプロイ

SSH でできること

MAESTRO は、エージェントが SSH 経由でリモートホストを操作するための 2 つの仕組みを持ちます。どちらも admin が有効化し、接続を登録してから使います。

仕組み	用途	対応 piece
ssh-ops	単発コマンド実行・ファイル転送 (health check / config push / log fetch)	ssh-ops
ssh-console	対話的な PTY シェル (vim / tmux / tail など長時間作業)	ssh-console

いずれもデフォルトでは無効です。admin が config.yaml で有効化し (ssh.enabled: true、コンソールは加えて ssh.console.enabled: true)、SSH 接続を登録したうえでジョブの所有者に grant を付与する必要があります。詳しくは 管理者ガイド を参照してください。

ssh-ops: 単発実行とファイル転送

ssh-ops piece は次の 3 軸をカバーする ops 向け piece です。

• Health check: uptime / df -h / free -m / プロセス状態 / journalctl などで状態を確認
• Config push: ローカルで作った設定を SshUpload で配信し、SshExec でリロード
• Log fetch: SshDownload でリモートのログを取得し、ローカルで grep / 集計 / 分析

使うツール: SshExec(単発コマンド) / SshUpload / SshDownload / SshListConnections。結果は output/report.md にまとめられます。機密値はコマンド文字列に直接書かず、レポートにも記録しません。

リモートへの書き込みは接続ごとの remote_path_prefix 配下に限られ、違反は path_not_allowed で拒否されます。出力が大きすぎてコマンド結果が truncated になる場合は、SshDownload でファイル経由に切り替えます。

ssh-console: 対話的な PTY シェル

ssh-console piece は、AI と人間が共有する 1 つの PTY セッションをタスクに開きます。両者がコマンドを打ち、同じ画面出力を見られます。次のようなケースに向きます。

• ログを tail しながらの作業
• vim / top / less / tmux など TUI が必要な操作
• 複数ラウンドにわたる対話的な調査

使うツール (3 つ):

• SshConsoleEnsure — セッションを開く (冪等)
• SshConsoleSend — キー入力を送る (\n 改行、\x03 Ctrl-C などの制御文字も送れる)
• SshConsoleSnapshot — 現在の画面 / scrollback を取得

ファイル転送 (SshUpload / SshDownload) は SFTP 経路で動き、PTY セッションとは独立しています。設定を置いてからコンソールでリロードコマンドを送る、といった組み合わせが可能です。

コンソールはアイドルや最大時間で自動クローズされます (既定でアイドル 30 分、最大 4 時間)。

コンソールを開く・見る

ssh-console piece でタスクを実行すると、エージェントがコンソールセッションを開きます。アクティブなセッションがある間、タスク詳細に「SSH」タブが現れ、ここでターミナル画面をリアルタイムに見て、人間が直接コマンドを打つこともできます。タスク詳細での見方・介入は 実行中のタスクを見る・介入する を参照してください。

SSH 接続プロファイルを登録する

接続は TopBar → ユーザーフォルダ → SSH 接続 から登録します。

1. 「+ 新規作成」で接続を作成 (label / host / user など)
2. 鍵の公開鍵をリモートの authorized_keys に登録
3. 「Test」を押してホストキーを検証する (TOFU: 初回接続で見たキーを記録)

ホストキー検証 (TOFU) を済ませないと、エージェント側は host_key_not_verified で停止します。検証後にキーが変わっていた場合は host_key_mismatch となり、MITM の疑いとして自動リトライせず中断します。

接続には個人接続と、admin が登録する全体接続があります。全体接続を使うには admin の grant が必要です。

どう動かすか

1. admin が SSH を有効化し、接続と grant を整える
2. ユーザーが該当接続を登録 (個人接続の場合) して Test でホストキーを検証
3. ssh-ops または ssh-console を使うタスクを作成して実行
4. ssh-console の場合はタスク詳細の SSH タブで画面を確認・操作

Piece の選び方や allowed_tools の考え方は piece を使う・作る を参照してください。

よくあるエラー

エラーコード	意味	対処
host_key_not_verified	TOFU 未完了	UI の Test で検証
host_key_mismatch	ホストキー不一致 (MITM 疑い)	自動リトライしない。管理者に確認
command_rejected	allow/deny リストで拒否	admin に許可パターン追加を相談 (ローカル回避しない)
path_not_allowed	remote_path_prefix 外への書き込み	許可パス内に変更
no_grant / access_denied	権限不足	admin に grant 追加を依頼
abuse_locked	連続失敗でロック	admin に force-unlock を依頼

詳しい運用手順は docs/ssh.md を参照してください。