# 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

```
LLM ──HTTPS──► Proxy SSH ──SSH──► macchine target
                (detiene le chiavi,
                 audit log,
                 limiti di rate)
```

Il proxy espone sessioni persistenti con una superficie REST semplice:

| Endpoint | Scopo |
|---|---|
| `POST /connect?target=vps1` | aprire una sessione → `session_id` |
| `POST /<sid>/exec` `{command, timeout}` | eseguire un comando (async) → `exec_id` |
| `GET /<sid>/exec/<exec_id>` | interrogare l'output |
| Endpoint SFTP | up/download di file, `ls`, `mkdir`, `rm` |

L'autenticazione è un token Bearer — lo stesso schema di ogni altra API che usi.

## Il pattern di esecuzione

```bash
# 1. connetti una volta, riusa la sessione per tutto il task
SID=$(curl -s -H "Authorization: Bearer $KEY" \
  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)

# 2. esegui un comando
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. interroga il risultato
curl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"
```

## Regole di ingaggio

1. **Riusa le sessioni.** Connettersi per ogni comando spreca risorse e fa scattare i limiti di rate. Salva il `session_id` (es. `/tmp/vps1_sid`) e fai heartbeat prima di riutilizzarlo.
2. **Nomina i target, non scoprili.** I target sono pre-registrati (`vps1`, `pi`, …). 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 `exec` 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. `exec` è fire-and-forget con timeout; usa `nohup` + 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 `timeout` o spezza il comando; verifica il carico del target |
| contenuto file corrotto | hai usato `exec` invece di SFTP — passa agli endpoint SFTP |