{"title":"Accès SSH via proxy","slug":"ssh-proxy-access","category":"llm-cookbook","summary":"Comment un agent LLM exécute des commandes sur des machines distantes en toute sécurité via une API de proxy SSH au lieu de clés SSH brutes.","audience":["llm"],"tags":["cookbook","ssh","proxy","infrastructure","remote-execution"],"difficulty":"intermediate","updated":"2026-09-26","word_count":418,"read_minutes":2,"llm_context":"Ne garde JAMAIS de clés privées SSH brutes en tant que LLM. Utilise une API HTTP de proxy SSH :\n1) POST /connect?target= → session_id (persistante, survit des heures).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → sortie quand c'est fini.\n4) Utilise les endpoints SFTP pour l'upload/download de fichiers au lieu de cat/heredoc.\nLes targets sont des noms pré-enregistrés (ex. \"vps1\"), pas des IPs — le proxy est\nle seul endroit où vivent les identifiants.\n","lang":"fr","translated":true,"requested_lang":"fr","content_markdown":"\n# Accès SSH via proxy\n\nLes 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.\n\n## Le modèle\n\n```\nLLM ──HTTPS──► Proxy SSH ──SSH──► machines cibles\n (détient les clés,\n journal d'audit,\n limites de débit)\n```\n\nLe proxy expose des sessions persistantes avec une surface REST simple :\n\n| Endpoint | Objectif |\n|---|---|\n| `POST /connect?target=vps1` | ouvrir une session → `session_id` |\n| `POST //exec` `{command, timeout}` | exécuter une commande (async) → `exec_id` |\n| `GET //exec/` | interroger la sortie |\n| Endpoints SFTP | up/download de fichiers, `ls`, `mkdir`, `rm` |\n\nL'authentification est un token Bearer — le même motif que toutes les autres API que tu utilises.\n\n## Le motif d'exécution\n\n```bash\n# 1. connecte-toi une fois, réutilise la session pour toute la tâche\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. exécute une commande\nEID=$(curl -s -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -X POST \"https://ssh-proxy.example/$SID/exec\" \\\n -d '{\"command\": \"docker ps --format \\\"{{.Names}}\\\"\", \"timeout\": 120}' | jq -r .exec_id)\n\n# 3. interroge le résultat\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Règles d'engagement\n\n1. **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.\n2. **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.\n3. **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.\n4. **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.\n5. **Suppose l'audit.** Chaque exec atterrit dans le journal d'audit du proxy — comporte-toi comme si l'humain lisait tout (il peut).\n\n## Quand NE PAS utiliser exec\n\n- 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.\n- Processus interactifs de longue durée. `exec` est fire-and-forget avec timeout ; utilise `nohup` + un fichier d'état sur la cible.\n- Tout ce qui est destructif sans instruction explicite. Le proxy te donne le pouvoir — l'humain te donne la permission.\n\n## Récupération d'erreurs\n\n| Symptôme | Solution |\n|---|---|\n| 401 au connect | token expiré — relis-le depuis memory/settings, jamais depuis une transcription |\n| session 404 | session expirée (plafond 24h) — reconnecte-toi |\n| timeout d'exec | augmente `timeout` ou découpe la commande ; vérifie la charge de la cible |\n| contenu de fichier corrompu | tu as utilisé `exec` au lieu de SFTP — passe aux endpoints SFTP |\n","content_html":"

Accès SSH via proxy

\n

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.

\n

Le modèle

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

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointObjectif
POST /connect?target=vps1ouvrir 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 SFTPup/download de fichiers, ls, mkdir, rm
\n

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

\n

Le motif d'exécution

\n
# 1. connecte-toi une fois, réutilise la session pour toute la tâche\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. exécute une commande\nEID=$(curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \\\n  -X POST "https://ssh-proxy.example/$SID/exec" \\\n  -d '{"command": "docker ps --format \\"{{.Names}}\\"", "timeout": 120}' | jq -r .exec_id)\n\n# 3. interroge le résultat\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Règles d'engagement

\n
    \n
  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. \n
  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. \n
  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. \n
  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. \n
  5. Suppose l'audit. Chaque exec atterrit dans le journal d'audit du proxy — comporte-toi comme si l'humain lisait tout (il peut).
    6. \n
\n

Quand NE PAS utiliser exec

\n
    \n
  • 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.
    • \n
  • Processus interactifs de longue durée. exec est fire-and-forget avec timeout ; utilise nohup + un fichier d'état sur la cible.
    • \n
  • Tout ce qui est destructif sans instruction explicite. Le proxy te donne le pouvoir — l'humain te donne la permission.
    • \n
\n

Récupération d'erreurs

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SymptômeSolution
401 au connecttoken expiré — relis-le depuis memory/settings, jamais depuis une transcription
session 404session expirée (plafond 24h) — reconnecte-toi
timeout d'execaugmente timeout ou découpe la commande ; vérifie la charge de la cible
contenu de fichier corromputu as utilisé exec au lieu de SFTP — passe aux endpoints SFTP
\n","urls":{"html":"/docs/llm-cookbook/ssh-proxy-access","text":"/docs/llm-cookbook/ssh-proxy-access?format=text","json":"/docs/llm-cookbook/ssh-proxy-access?format=json","llm":"/docs/llm-cookbook/ssh-proxy-access?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"],"wordCount":418,"readMinutes":2,"llmContext":"Ne garde JAMAIS de clés privées SSH brutes en tant que LLM. Utilise une API HTTP de proxy SSH :\n1) POST /connect?target= → session_id (persistante, survit des heures).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → sortie quand c'est fini.\n4) Utilise les endpoints SFTP pour l'upload/download de fichiers au lieu de cat/heredoc.\nLes targets sont des noms pré-enregistrés (ex. \"vps1\"), pas des IPs — le proxy est\nle seul endroit où vivent les identifiants.\n","requestedLang":"fr","contentMarkdown":"\n# Accès SSH via proxy\n\nLes 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.\n\n## Le modèle\n\n```\nLLM ──HTTPS──► Proxy SSH ──SSH──► machines cibles\n (détient les clés,\n journal d'audit,\n limites de débit)\n```\n\nLe proxy expose des sessions persistantes avec une surface REST simple :\n\n| Endpoint | Objectif |\n|---|---|\n| `POST /connect?target=vps1` | ouvrir une session → `session_id` |\n| `POST //exec` `{command, timeout}` | exécuter une commande (async) → `exec_id` |\n| `GET //exec/` | interroger la sortie |\n| Endpoints SFTP | up/download de fichiers, `ls`, `mkdir`, `rm` |\n\nL'authentification est un token Bearer — le même motif que toutes les autres API que tu utilises.\n\n## Le motif d'exécution\n\n```bash\n# 1. connecte-toi une fois, réutilise la session pour toute la tâche\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. exécute une commande\nEID=$(curl -s -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -X POST \"https://ssh-proxy.example/$SID/exec\" \\\n -d '{\"command\": \"docker ps --format \\\"{{.Names}}\\\"\", \"timeout\": 120}' | jq -r .exec_id)\n\n# 3. interroge le résultat\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Règles d'engagement\n\n1. **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.\n2. **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.\n3. **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.\n4. **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.\n5. **Suppose l'audit.** Chaque exec atterrit dans le journal d'audit du proxy — comporte-toi comme si l'humain lisait tout (il peut).\n\n## Quand NE PAS utiliser exec\n\n- 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.\n- Processus interactifs de longue durée. `exec` est fire-and-forget avec timeout ; utilise `nohup` + un fichier d'état sur la cible.\n- Tout ce qui est destructif sans instruction explicite. Le proxy te donne le pouvoir — l'humain te donne la permission.\n\n## Récupération d'erreurs\n\n| Symptôme | Solution |\n|---|---|\n| 401 au connect | token expiré — relis-le depuis memory/settings, jamais depuis une transcription |\n| session 404 | session expirée (plafond 24h) — reconnecte-toi |\n| timeout d'exec | augmente `timeout` ou découpe la commande ; vérifie la charge de la cible |\n| contenu de fichier corrompu | tu as utilisé `exec` au lieu de SFTP — passe aux endpoints SFTP |\n","contentHtml":"

Accès SSH via proxy

\n

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.

\n

Le modèle

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

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointObjectif
POST /connect?target=vps1ouvrir 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 SFTPup/download de fichiers, ls, mkdir, rm
\n

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

\n

Le motif d'exécution

\n
# 1. connecte-toi une fois, réutilise la session pour toute la tâche\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. exécute une commande\nEID=$(curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \\\n  -X POST "https://ssh-proxy.example/$SID/exec" \\\n  -d '{"command": "docker ps --format \\"{{.Names}}\\"", "timeout": 120}' | jq -r .exec_id)\n\n# 3. interroge le résultat\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Règles d'engagement

\n
    \n
  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. \n
  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. \n
  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. \n
  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. \n
  5. Suppose l'audit. Chaque exec atterrit dans le journal d'audit du proxy — comporte-toi comme si l'humain lisait tout (il peut).
    6. \n
\n

Quand NE PAS utiliser exec

\n
    \n
  • 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.
    • \n
  • Processus interactifs de longue durée. exec est fire-and-forget avec timeout ; utilise nohup + un fichier d'état sur la cible.
    • \n
  • Tout ce qui est destructif sans instruction explicite. Le proxy te donne le pouvoir — l'humain te donne la permission.
    • \n
\n

Récupération d'erreurs

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SymptômeSolution
401 au connecttoken expiré — relis-le depuis memory/settings, jamais depuis une transcription
session 404session expirée (plafond 24h) — reconnecte-toi
timeout d'execaugmente timeout ou découpe la commande ; vérifie la charge de la cible
contenu de fichier corromputu as utilisé exec au lieu de SFTP — passe aux endpoints SFTP
\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}