# Accès SSH via proxy

Les agents doivent exécuter des commandes sur des machines distantes — déployer un conteneur, lire un log, corriger une config. Remettre des clés privées SSH brutes à un LLM est une mauvaise idée : les clés finissent dans les fenêtres de contexte, les logs et les transcriptions. Un proxy SSH résout cela : il détient les identifiants, l'agent ne parle qu'en HTTP.

## Le modèle

```
LLM ──HTTPS──► Proxy SSH ──SSH──► machines cibles
                (détient les clés,
                 journal d'audit,
                 limites de débit)
```

Le proxy expose des sessions persistantes avec une surface REST simple :

| Endpoint | Objectif |
|---|---|
| `POST /connect?target=vps1` | ouvrir une session → `session_id` |
| `POST /<sid>/exec` `{command, timeout}` | exécuter une commande (async) → `exec_id` |
| `GET /<sid>/exec/<exec_id>` | interroger la sortie |
| Endpoints SFTP | up/download de fichiers, `ls`, `mkdir`, `rm` |

L'authentification est un token Bearer — le même motif que toutes les autres API que tu utilises.

## Le motif d'exécution

```bash
# 1. connecte-toi une fois, réutilise la session pour toute la tâche
SID=$(curl -s -H "Authorization: Bearer $KEY" \
  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)

# 2. exécute une commande
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. interroge le résultat
curl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"
```

## Règles d'engagement

1. **Réutilise les sessions.** Se connecter par commande gaspille des ressources et déclenche les limites de débit. Stocke le `session_id` (ex. `/tmp/vps1_sid`) et fais-lui un heartbeat avant réutilisation.
2. **Nomme les targets, ne les découvre pas.** Les targets sont pré-enregistrés (`vps1`, `pi`, …). Le proxy est la source unique de vérité — n'intègre jamais d'adresses IP en dur dans le code d'agent.
3. **Préfère SFTP à cat/heredoc de shell pour les fichiers.** Échapper des données binaires via `exec` corrompt les payloads. Utilise les endpoints dédiés d'upload/download.
4. **Cite tes commandes.** Le corps JSON est parsé deux fois (HTTP + shell). Enveloppe les commandes distantes dans des guillemets simples et garde-les sur une ligne.
5. **Suppose l'audit.** Chaque exec atterrit dans le journal d'audit du proxy — comporte-toi comme si l'humain lisait tout (il peut).

## Quand NE PAS utiliser exec

- Lire un état structuré qui a une API (Docker, bases de données, la Mind API de Synapse) — préfère toujours l'API au parsing de sortie CLI.
- Processus interactifs de longue durée. `exec` est fire-and-forget avec timeout ; utilise `nohup` + un fichier d'état sur la cible.
- Tout ce qui est destructif sans instruction explicite. Le proxy te donne le pouvoir — l'humain te donne la permission.

## Récupération d'erreurs

| Symptôme | Solution |
|---|---|
| 401 au connect | token expiré — relis-le depuis memory/settings, jamais depuis une transcription |
| session 404 | session expirée (plafond 24h) — reconnecte-toi |
| timeout d'exec | augmente `timeout` ou découpe la commande ; vérifie la charge de la cible |
| contenu de fichier corrompu | tu as utilisé `exec` au lieu de SFTP — passe aux endpoints SFTP |