# 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-эндпоинты |