---
id: ssh
title: SSH リモート操作
category: advanced
order: 140
keywords: [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`）を設定します。詳しくは [管理者ガイド](./19-admin.md) を参照してください。
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」タブが現れ、ここでターミナル画面をリアルタイムに見て、人間が直接コマンドを打つこともできます。タスク詳細での見方・介入は [実行中のタスクを見る・介入する](./03-running.md) を参照してください。

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

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 を使う・作る](./05-pieces.md) を参照してください。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` を参照してください。