# SSH-доступ через проксі
SUMMARY: Як LLM-агент безпечно виконує команди на віддалених машинах через HTTP-API SSH-проксі замість сирих SSH-ключів.

KEY CONTEXT:
НІКОЛИ не тримайте сирі приватні SSH-ключі як LLM. Використовуйте HTTP-API SSH-проксі:
1) POST /connect?target=<name> → session_id (постійна, живе годинами).
2) POST /<session_id>/exec {command, timeout} → exec_id.
3) GET /<session_id>/exec/<exec_id> → вивід після завершення.
4) Для завантаження/відправлення файлів використовуйте SFTP-ендпоінти замість cat/heredoc.
Цілі — попередньо зареєстровані імена (напр. "vps1"), не IP — проксі — єдине
місце, де живуть облікові дані.

SSH-доступ через проксі
Агентам потрібно виконувати команди на віддалених машинах — розгорнути контейнер, прочитати лог, виправити конфіг. Давати сирі приватні SSH-ключі LLM — погана ідея: ключі потрапляють у вікна контексту, логи й транскрипти. SSH-проксі вирішує це: облікові дані зберігає він, агент говорить лише HTTP.
Модель
[CODE BLOCK]
Проксі віддає постійні сесії через просту REST-поверхню:
| Ендпоінт | Призначення |
|---|---|
|  | відкрити сесію →  |
|   | виконати команду (async) →  |
|  | опитати вивід |
| SFTP-ендпоінти | завантаження/відправлення файлів, , ,  |
Аутентифікація — Bearer-токен, той самий патерн, що й в усіх інших API, які ви використовуєте.
Патерн виконання
[CODE BLOCK]
Правила поведінки
1. Перевикористовуйте сесії. Підключення на кожну команду марнує ресурси й ловить ліміти частоти. Збережіть  (напр. ) і перевіряйте його heartbeat перед повторним використанням.
2. Називайте цілі, а не відкривайте їх. Цілі попередньо зареєстровані (, , …). Проксі — єдине джерело правди; ніколи не зашивайте IP-адреси в код агента.
3. Надавайте перевагу SFTP замість cat/heredoc для файлів. Екранування бінарних даних через  псує навантаження. Використовуйте виділені ендпоінти завантаження/відправлення.
4. Кавичте свої команди. Тіло JSON парситься двічі (HTTP + shell). Обгортайте віддалені команди в одинарні лапки й тримайте їх в один рядок.
5. Вважайте, що аудит ведеться. Кожен exec потрапляє в журнал аудиту проксі — ведіть себе так, ніби людина читає все (вона може).
Коли exec використовувати НЕ варто
- Читання структурованого стану, який має API (Docker, бази даних, Mind API Synapse) — завжди надавайте перевагу API розбору виводу CLI.
- Довгі інтерактивні процеси.  — це fire-and-forget з таймаутом; натомість використовуйте  + файл статусу на цільовій машині.
- Будь-яке деструктивне дійство без явної інструкції. Проксі дає вам владу — людина дає вам дозвіл.
Відновлення після помилок
| Симптом | Рішення |
|---|---|
| 401 при connect | токен минув — перечитайте його з memory/settings, ніколи з транскрипту |
| сесія 404 | сесія минула (ліміт 24 год) — перепідключіться |
| таймаут exec | підніміть  або розділіть команду; перевірте навантаження цільової машини |
| зіпсований вміст файлу | ви використали  замість SFTP — перейдіть на SFTP-ендпоінти |