# SSH-доступ через проксі

Агентам потрібно виконувати команди на віддалених машинах — розгорнути контейнер, прочитати лог, виправити конфіг. Давати сирі приватні SSH-ключі LLM — погана ідея: ключі потрапляють у вікна контексту, логи й транскрипти. SSH-проксі вирішує це: облікові дані зберігає він, агент говорить лише HTTP.

## Модель

```
LLM ──HTTPS──► SSH-проксі ──SSH──► цільові машини
                (зберігає ключі,
                 журнал аудиту,
                 ліміти частоти)
```

Проксі віддає постійні сесії через просту REST-поверхню:

| Ендпоінт | Призначення |
|---|---|
| `POST /connect?target=vps1` | відкрити сесію → `session_id` |
| `POST /<sid>/exec` `{command, timeout}` | виконати команду (async) → `exec_id` |
| `GET /<sid>/exec/<exec_id>` | опитати вивід |
| SFTP-ендпоінти | завантаження/відправлення файлів, `ls`, `mkdir`, `rm` |

Аутентифікація — Bearer-токен, той самий патерн, що й в усіх інших API, які ви використовуєте.

## Патерн виконання

```bash
# 1. підключіться один раз, перевикористайте сесію для всієї задачі
SID=$(curl -s -H "Authorization: Bearer $KEY" \
  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)

# 2. виконайте команду
EID=$(curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -X POST "https://ssh-proxy.example/$SID/exec" \
  -d '{"command": "docker ps --format \"{{.Names}}\"", "timeout": 120}' | jq -r .exec_id)

# 3. опитайте результат
curl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"
```

## Правила поведінки

1. **Перевикористовуйте сесії.** Підключення на кожну команду марнує ресурси й ловить ліміти частоти. Збережіть `session_id` (напр. `/tmp/vps1_sid`) і перевіряйте його heartbeat перед повторним використанням.
2. **Називайте цілі, а не відкривайте їх.** Цілі попередньо зареєстровані (`vps1`, `pi`, …). Проксі — єдине джерело правди; ніколи не зашивайте IP-адреси в код агента.
3. **Надавайте перевагу SFTP замість cat/heredoc для файлів.** Екранування бінарних даних через `exec` псує навантаження. Використовуйте виділені ендпоінти завантаження/відправлення.
4. **Кавичте свої команди.** Тіло JSON парситься двічі (HTTP + shell). Обгортайте віддалені команди в одинарні лапки й тримайте їх в один рядок.
5. **Вважайте, що аудит ведеться.** Кожен exec потрапляє в журнал аудиту проксі — ведіть себе так, ніби людина читає все (вона може).

## Коли exec використовувати НЕ варто

- Читання структурованого стану, який має API (Docker, бази даних, Mind API Synapse) — завжди надавайте перевагу API розбору виводу CLI.
- Довгі інтерактивні процеси. `exec` — це fire-and-forget з таймаутом; натомість використовуйте `nohup` + файл статусу на цільовій машині.
- Будь-яке деструктивне дійство без явної інструкції. Проксі дає вам владу — людина дає вам дозвіл.

## Відновлення після помилок

| Симптом | Рішення |
|---|---|
| 401 при connect | токен минув — перечитайте його з memory/settings, ніколи з транскрипту |
| сесія 404 | сесія минула (ліміт 24 год) — перепідключіться |
| таймаут exec | підніміть `timeout` або розділіть команду; перевірте навантаження цільової машини |
| зіпсований вміст файлу | ви використали `exec` замість SFTP — перейдіть на SFTP-ендпоінти |