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

いずれもデフォルトでは無効です。使い始めるには次の 2 つの条件を満たす必要があります。

1. admin が SSH を有効化する — config.yaml で ssh.enabled: true（コンソールは加えて ssh.console.enabled: true）を設定します。詳しくは 管理者ガイド を参照してください。
2. ワークスペースポリシーで SSH を有効にし、接続を登録する — ワークスペースの 設定 → ツール で ssh カテゴリをオンにし、設定 → SSH で接続を登録します。エージェントはそのワークスペースに登録された接続のみ使えます（他のワークスペースの接続には触れません）。

スコープ設計: 接続の登録がオプトインです。ワークスペースに登録された接続だけがそのワークスペースのタスクから見え、別ワークスペースへの水平移動はできません。MCP サーバーのスコープと同じ考え方です。

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」タブが現れ、ここでターミナル画面をリアルタイムに見て、人間が直接コマンドを打つこともできます。タスク詳細での見方・介入は 実行中のタスクを見る・介入する を参照してください。

複数のセッションを同時に開く

1 つのタスクで、複数の SSH 接続に同時にセッションを開けます。SSH タブの上部には接続ごとのタブが並び、クリックで切り替えられます。各タブには接続名と、状態を示す丸（接続中 / アイドル / 切断）が付き、エージェントがそのセッションを操作している間は ⚡ が点灯します。

• ＋ 接続 ボタンを押すと、別の接続を選んで新しいセッションを追加できます。既存のタブは閉じません
• 不要になったセッションはタブの ✕ で閉じられます。閉じられるのは、そのセッションを開いた本人か、ワークスペースのオーナー・管理者だけです
• 画面をリアルタイムに流し続けるのは、いま選んでいるタブだけです。他のタブに切り替えると、それまでの出力（scrollback）を巻き戻して表示します
• エージェントが別の接続を開いたり切り替えたりしても、いま見ている画面は変わりません。 表示が切り替わるのは、ユーザー自身がタブをクリックしたときだけです
• 同時に開けるセッション数には上限があります（既定 5。admin の設定次第でユーザー単位の上限も加わります）。上限に達すると新しいセッションは開けず、使っていないタブを閉じるよう案内が出ます

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

接続は、ワークスペースを開いて 設定 → SSH から登録します（旧「ユーザーフォルダ → 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 が config.yaml で SSH を有効化する
2. ワークスペースの 設定 → ツール で ssh カテゴリをオンにする
3. 設定 → SSH で接続を登録し、Test でホストキーを検証する
4. ssh-ops または ssh-console を使うタスクを作成して実行する
5. ssh-console の場合はタスク詳細の SSH タブで画面を確認・操作する

Piece の選び方は piece を使う・作る を参照してください。SSH 接続の可否はワークスペースの 設定 → ツール／SSH で決まります（Piece には書きません）。

他のワークスペースから取り込む

同じ MAESTRO 内の別ワークスペースに登録済みの SSH 接続を、まとめてコピーできます。設定 → SSH の「他のワークスペースから取り込む」ボタンを押すと、自分が管理しているワークスペースの一覧が出るので、コピー元を選んで実行してください。

• 操作できる条件: 取り込み元と移し先の両方でオーナー・管理者であること
• スキップ: 同じ label・同じ host/user の組み合わせがすでにある場合は自動でスキップされ、既存の接続は上書きされません
• 秘密鍵ごとコピー: 秘密鍵は移し先ワークスペースの鍵で再暗号化されて保存されます。取り込み後すぐに使えますが、ホストキー検証（TOFU）が未完了の接続は Test を押して検証してください
• 同一サーバー内のみ: 別環境（別インスタンス）へのエクスポートには対応していません

よくあるエラー

エラーコード	意味	対処
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 を参照してください。