{"title":"SSH-toegang via proxy","slug":"ssh-proxy-access","category":"llm-cookbook","summary":"Hoe een LLM-agent veilig commando's uitvoert op externe machines via een SSH-proxy-API in plaats van rauwe SSH-sleutels.","audience":["llm"],"tags":["cookbook","ssh","proxy","infrastructure","remote-execution"],"difficulty":"intermediate","updated":"2026-09-26","word_count":363,"read_minutes":2,"llm_context":"Houd N O O I T rauwe SSH-privésleutels als LLM. Gebruik een SSH-proxy-HTTP-API:\n1) POST /connect?target= → session_id (persistent, overleeft uren).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → output wanneer klaar.\n4) Gebruik SFTP-endpoints voor bestandsup-/download in plaats van cat/heredoc.\nTargets zijn vooraf geregistreerde namen (bijv. \"vps1\"), geen IP's — de proxy is\nde enige plek waar credentials leven.\n","lang":"nl","translated":true,"requested_lang":"nl","content_markdown":"\n# SSH-toegang via proxy\n\nAgenten moeten commando's uitvoeren op externe machines — een container deployen, een log lezen, een config repareren. Rauwe SSH-privésleutels aan een LLM geven is een slecht idee: sleutels belanden in contextvensters, logs en transcripties. Een SSH-proxy lost dit op: hij bezit de credentials, de agent spreekt alleen HTTP.\n\n## Het model\n\n```\nLLM ──HTTPS──► SSH-proxy ──SSH──► doelmachines\n (bezit sleutels,\n auditlog,\n ratelimieten)\n```\n\nDe proxy stelt persistente sessies bloot met een eenvoudig REST-oppervlak:\n\n| Endpoint | Doel |\n|---|---|\n| `POST /connect?target=vps1` | een sessie openen → `session_id` |\n| `POST //exec` `{command, timeout}` | een commando uitvoeren (async) → `exec_id` |\n| `GET //exec/` | output opvragen |\n| SFTP-endpoints | bestandsup-/download, `ls`, `mkdir`, `rm` |\n\nAuth is een Bearer-token — hetzelfde patroon als elke andere API die je gebruikt.\n\n## Het uitvoeringspatroon\n\n```bash\n# 1. verbind een keer, hergebruik de sessie voor de hele taak\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. voer een commando uit\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. vraag het resultaat op\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Gedragsregels\n\n1. **Hergebruik sessies.** Per commando verbinden verspilt bronnen en triggert ratelimieten. Bewaar de `session_id` (bijv. `/tmp/vps1_sid`) en geef hem een heartbeat vóór hergebruik.\n2. **Noem targets, ontdek ze niet.** Targets zijn vooraf geregistreerd (`vps1`, `pi`, …). De proxy is de enige bron van waarheid — hardcode nooit IP-adressen in agentcode.\n3. **Geef SFTP de voorkeur boven shell cat/heredoc voor bestanden.** Escapen van binaire data via `exec` corrumpeert payloads. Gebruik de dedicated upload/download-endpoints.\n4. **Quote je commando's.** De JSON-body wordt twee keer geparsed (HTTP + shell). Wikkel externe commando's in enkele aanhalingstekens en houd ze éénregelig.\n5. **Reken op auditing.** Elke exec komt in het auditlog van de proxy — gedraag je alsof de mens alles leest (dat kan).\n\n## Wanneer exec NIET gebruiken\n\n- Gestructureerde staat lezen die een API heeft (Docker, databases, de Synapse Mind API) — geef altijd de API de voorkeur boven CLI-output parsen.\n- Langlopende interactieve processen. `exec` is fire-and-forget met timeout; gebruik `nohup` + een statusbestand op de target.\n- Alles destructiefs zonder expliciete instructie. De proxy geeft je de kracht — de mens geeft je de toestemming.\n\n## Foutenherstel\n\n| Symptoom | Oplossing |\n|---|---|\n| 401 bij connect | token verlopen — lees hem opnieuw uit memory/settings, nooit uit een transcript |\n| sessie 404 | sessie verlopen (24h-limiet) — verbind opnieuw |\n| exec-timeout | verhoog `timeout` of splits het commando; controleer de belasting van de target |\n| gecorrumpeerde bestandsinhoud | je gebruikte `exec` in plaats van SFTP — schakel over naar de SFTP-endpoints |\n","content_html":"

SSH-toegang via proxy

\n

Agenten moeten commando's uitvoeren op externe machines — een container deployen, een log lezen, een config repareren. Rauwe SSH-privésleutels aan een LLM geven is een slecht idee: sleutels belanden in contextvensters, logs en transcripties. Een SSH-proxy lost dit op: hij bezit de credentials, de agent spreekt alleen HTTP.

\n

Het model

\n
LLM ──HTTPS──► SSH-proxy ──SSH──► doelmachines\n                (bezit sleutels,\n                 auditlog,\n                 ratelimieten)

De proxy stelt persistente sessies bloot met een eenvoudig REST-oppervlak:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointDoel
POST /connect?target=vps1een sessie openen → session_id
POST /<sid>/exec {command, timeout}een commando uitvoeren (async) → exec_id
GET /<sid>/exec/<exec_id>output opvragen
SFTP-endpointsbestandsup-/download, ls, mkdir, rm
\n

Auth is een Bearer-token — hetzelfde patroon als elke andere API die je gebruikt.

\n

Het uitvoeringspatroon

\n
# 1. verbind een keer, hergebruik de sessie voor de hele taak\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. voer een commando uit\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. vraag het resultaat op\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Gedragsregels

\n
    \n
  1. Hergebruik sessies. Per commando verbinden verspilt bronnen en triggert ratelimieten. Bewaar de session_id (bijv. /tmp/vps1_sid) en geef hem een heartbeat vóór hergebruik.
    2. \n
  2. Noem targets, ontdek ze niet. Targets zijn vooraf geregistreerd (vps1, pi, …). De proxy is de enige bron van waarheid — hardcode nooit IP-adressen in agentcode.
    3. \n
  3. Geef SFTP de voorkeur boven shell cat/heredoc voor bestanden. Escapen van binaire data via exec corrumpeert payloads. Gebruik de dedicated upload/download-endpoints.
    4. \n
  4. Quote je commando's. De JSON-body wordt twee keer geparsed (HTTP + shell). Wikkel externe commando's in enkele aanhalingstekens en houd ze éénregelig.
    5. \n
  5. Reken op auditing. Elke exec komt in het auditlog van de proxy — gedraag je alsof de mens alles leest (dat kan).
    6. \n
\n

Wanneer exec NIET gebruiken

\n
    \n
  • Gestructureerde staat lezen die een API heeft (Docker, databases, de Synapse Mind API) — geef altijd de API de voorkeur boven CLI-output parsen.
    • \n
  • Langlopende interactieve processen. exec is fire-and-forget met timeout; gebruik nohup + een statusbestand op de target.
    • \n
  • Alles destructiefs zonder expliciete instructie. De proxy geeft je de kracht — de mens geeft je de toestemming.
    • \n
\n

Foutenherstel

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SymptoomOplossing
401 bij connecttoken verlopen — lees hem opnieuw uit memory/settings, nooit uit een transcript
sessie 404sessie verlopen (24h-limiet) — verbind opnieuw
exec-timeoutverhoog timeout of splits het commando; controleer de belasting van de target
gecorrumpeerde bestandsinhoudje gebruikte exec in plaats van SFTP — schakel over naar de SFTP-endpoints
\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":363,"readMinutes":2,"llmContext":"Houd N O O I T rauwe SSH-privésleutels als LLM. Gebruik een SSH-proxy-HTTP-API:\n1) POST /connect?target= → session_id (persistent, overleeft uren).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → output wanneer klaar.\n4) Gebruik SFTP-endpoints voor bestandsup-/download in plaats van cat/heredoc.\nTargets zijn vooraf geregistreerde namen (bijv. \"vps1\"), geen IP's — de proxy is\nde enige plek waar credentials leven.\n","requestedLang":"nl","contentMarkdown":"\n# SSH-toegang via proxy\n\nAgenten moeten commando's uitvoeren op externe machines — een container deployen, een log lezen, een config repareren. Rauwe SSH-privésleutels aan een LLM geven is een slecht idee: sleutels belanden in contextvensters, logs en transcripties. Een SSH-proxy lost dit op: hij bezit de credentials, de agent spreekt alleen HTTP.\n\n## Het model\n\n```\nLLM ──HTTPS──► SSH-proxy ──SSH──► doelmachines\n (bezit sleutels,\n auditlog,\n ratelimieten)\n```\n\nDe proxy stelt persistente sessies bloot met een eenvoudig REST-oppervlak:\n\n| Endpoint | Doel |\n|---|---|\n| `POST /connect?target=vps1` | een sessie openen → `session_id` |\n| `POST //exec` `{command, timeout}` | een commando uitvoeren (async) → `exec_id` |\n| `GET //exec/` | output opvragen |\n| SFTP-endpoints | bestandsup-/download, `ls`, `mkdir`, `rm` |\n\nAuth is een Bearer-token — hetzelfde patroon als elke andere API die je gebruikt.\n\n## Het uitvoeringspatroon\n\n```bash\n# 1. verbind een keer, hergebruik de sessie voor de hele taak\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. voer een commando uit\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. vraag het resultaat op\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Gedragsregels\n\n1. **Hergebruik sessies.** Per commando verbinden verspilt bronnen en triggert ratelimieten. Bewaar de `session_id` (bijv. `/tmp/vps1_sid`) en geef hem een heartbeat vóór hergebruik.\n2. **Noem targets, ontdek ze niet.** Targets zijn vooraf geregistreerd (`vps1`, `pi`, …). De proxy is de enige bron van waarheid — hardcode nooit IP-adressen in agentcode.\n3. **Geef SFTP de voorkeur boven shell cat/heredoc voor bestanden.** Escapen van binaire data via `exec` corrumpeert payloads. Gebruik de dedicated upload/download-endpoints.\n4. **Quote je commando's.** De JSON-body wordt twee keer geparsed (HTTP + shell). Wikkel externe commando's in enkele aanhalingstekens en houd ze éénregelig.\n5. **Reken op auditing.** Elke exec komt in het auditlog van de proxy — gedraag je alsof de mens alles leest (dat kan).\n\n## Wanneer exec NIET gebruiken\n\n- Gestructureerde staat lezen die een API heeft (Docker, databases, de Synapse Mind API) — geef altijd de API de voorkeur boven CLI-output parsen.\n- Langlopende interactieve processen. `exec` is fire-and-forget met timeout; gebruik `nohup` + een statusbestand op de target.\n- Alles destructiefs zonder expliciete instructie. De proxy geeft je de kracht — de mens geeft je de toestemming.\n\n## Foutenherstel\n\n| Symptoom | Oplossing |\n|---|---|\n| 401 bij connect | token verlopen — lees hem opnieuw uit memory/settings, nooit uit een transcript |\n| sessie 404 | sessie verlopen (24h-limiet) — verbind opnieuw |\n| exec-timeout | verhoog `timeout` of splits het commando; controleer de belasting van de target |\n| gecorrumpeerde bestandsinhoud | je gebruikte `exec` in plaats van SFTP — schakel over naar de SFTP-endpoints |\n","contentHtml":"

SSH-toegang via proxy

\n

Agenten moeten commando's uitvoeren op externe machines — een container deployen, een log lezen, een config repareren. Rauwe SSH-privésleutels aan een LLM geven is een slecht idee: sleutels belanden in contextvensters, logs en transcripties. Een SSH-proxy lost dit op: hij bezit de credentials, de agent spreekt alleen HTTP.

\n

Het model

\n
LLM ──HTTPS──► SSH-proxy ──SSH──► doelmachines\n                (bezit sleutels,\n                 auditlog,\n                 ratelimieten)

De proxy stelt persistente sessies bloot met een eenvoudig REST-oppervlak:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointDoel
POST /connect?target=vps1een sessie openen → session_id
POST /<sid>/exec {command, timeout}een commando uitvoeren (async) → exec_id
GET /<sid>/exec/<exec_id>output opvragen
SFTP-endpointsbestandsup-/download, ls, mkdir, rm
\n

Auth is een Bearer-token — hetzelfde patroon als elke andere API die je gebruikt.

\n

Het uitvoeringspatroon

\n
# 1. verbind een keer, hergebruik de sessie voor de hele taak\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. voer een commando uit\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. vraag het resultaat op\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Gedragsregels

\n
    \n
  1. Hergebruik sessies. Per commando verbinden verspilt bronnen en triggert ratelimieten. Bewaar de session_id (bijv. /tmp/vps1_sid) en geef hem een heartbeat vóór hergebruik.
    2. \n
  2. Noem targets, ontdek ze niet. Targets zijn vooraf geregistreerd (vps1, pi, …). De proxy is de enige bron van waarheid — hardcode nooit IP-adressen in agentcode.
    3. \n
  3. Geef SFTP de voorkeur boven shell cat/heredoc voor bestanden. Escapen van binaire data via exec corrumpeert payloads. Gebruik de dedicated upload/download-endpoints.
    4. \n
  4. Quote je commando's. De JSON-body wordt twee keer geparsed (HTTP + shell). Wikkel externe commando's in enkele aanhalingstekens en houd ze éénregelig.
    5. \n
  5. Reken op auditing. Elke exec komt in het auditlog van de proxy — gedraag je alsof de mens alles leest (dat kan).
    6. \n
\n

Wanneer exec NIET gebruiken

\n
    \n
  • Gestructureerde staat lezen die een API heeft (Docker, databases, de Synapse Mind API) — geef altijd de API de voorkeur boven CLI-output parsen.
    • \n
  • Langlopende interactieve processen. exec is fire-and-forget met timeout; gebruik nohup + een statusbestand op de target.
    • \n
  • Alles destructiefs zonder expliciete instructie. De proxy geeft je de kracht — de mens geeft je de toestemming.
    • \n
\n

Foutenherstel

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SymptoomOplossing
401 bij connecttoken verlopen — lees hem opnieuw uit memory/settings, nooit uit een transcript
sessie 404sessie verlopen (24h-limiet) — verbind opnieuw
exec-timeoutverhoog timeout of splits het commando; controleer de belasting van de target
gecorrumpeerde bestandsinhoudje gebruikte exec in plaats van SFTP — schakel over naar de SFTP-endpoints
\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}