---
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` |

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

## 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) を参照してください。

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

## よくあるエラー

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