# Accesso SSH via proxy
SUMMARY: Come un agente LLM esegue comandi su macchine remote in sicurezza tramite un'API proxy SSH invece di chiavi SSH grezze.

KEY CONTEXT:
NON tenere MAI chiavi private SSH grezze come LLM. Usa un'API HTTP proxy SSH:
1) POST /connect?target=<name> → session_id (persistente, sopravvive ore).
2) POST /<session_id>/exec {command, timeout} → exec_id.
3) GET /<session_id>/exec/<exec_id> → output a fine esecuzione.
4) Usa gli endpoint SFTP per up/download di file invece di cat/heredoc.
I target sono nomi pre-registrati (es. "vps1"), non IP — il proxy è l'unico
posto in cui vivono le credenziali.

Accesso SSH via proxy
Gli agenti devono eseguire comandi su macchine remote — deployare un container, leggere un log, correggere una config. Consegnare chiavi private SSH grezze a un LLM è una cattiva idea: le chiavi finiscono in finestre di contesto, log e trascrizioni. Un proxy SSH risolve il problema: le credenziali le detiene lui, l'agente parla solo HTTP.
Il modello
[CODE BLOCK]
Il proxy espone sessioni persistenti con una superficie REST semplice:
| Endpoint | Scopo |
|---|---|
|  | aprire una sessione →  |
|   | eseguire un comando (async) →  |
|  | interrogare l'output |
| Endpoint SFTP | up/download di file, , ,  |
L'autenticazione è un token Bearer — lo stesso schema di ogni altra API che usi.
Il pattern di esecuzione
[CODE BLOCK]
Regole di ingaggio
1. Riusa le sessioni. Connettersi per ogni comando spreca risorse e fa scattare i limiti di rate. Salva il  (es. ) e fai heartbeat prima di riutilizzarlo.
2. Nomina i target, non scoprili. I target sono pre-registrati (, , …). Il proxy è la fonte unica di verità — non hardcodare mai indirizzi IP nel codice agente.
3. Preferisci SFTP a cat/heredoc di shell per i file. L'escaping di dati binari via  corrompe i payload. Usa gli endpoint dedicati di upload/download.
4. Virgoletta i comandi. Il corpo JSON viene parsato due volte (HTTP + shell). Avvolgi i comandi remoti in apici singoli e tienili su una riga.
5. Assumi l'auditing. Ogni exec finisce nell'audit log del proxy — comportati come se l'umano leggesse tutto (può farlo).
Quando NON usare exec
- Leggere stato strutturato che ha una API (Docker, database, la Mind API di Synapse) — preferisci sempre la API al parsing dell'output CLI.
- Processi interattivi di lunga durata.  è fire-and-forget con timeout; usa  + un file di stato sul target.
- Qualsiasi cosa distruttiva senza istruzione esplicita. Il proxy ti dà il potere — l'umano ti dà il permesso.
Recupero errori
| Sintomo | Rimedio |
|---|---|
| 401 al connect | token scaduto — rileggilo da memory/settings, mai da una trascrizione |
| sessione 404 | sessione scaduta (limite 24h) — riconnetti |
| timeout dell'exec | alza  o spezza il comando; verifica il carico del target |
| contenuto file corrotto | hai usato  invece di SFTP — passa agli endpoint SFTP |