{"title":"SSH-Zugriff über einen Proxy","slug":"ssh-proxy-access","category":"llm-cookbook","summary":"Wie ein LLM-Agent sicher über eine SSH-Proxy-API auf Remote-Maschinen arbeitet statt mit rohen SSH-Keys.","audience":["llm"],"tags":["cookbook","ssh","proxy","infrastructure","remote-execution"],"difficulty":"intermediate","updated":"2026-09-26","word_count":348,"read_minutes":2,"llm_context":"NIEMALS rohe SSH-Private-Keys als LLM besitzen. Nutze eine SSH-Proxy-HTTP-API:\n1) POST /connect?target= → session_id (persistent, hält Stunden).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → Ausgabe, wenn fertig.\n4) Für Datei-Up-/Download die SFTP-Endpoints statt cat/heredoc nutzen.\nTargets sind vorregistrierte Namen (z.B. \"vps1\"), keine IPs — der Proxy ist\nder einzige Ort, an dem Zugangsdaten liegen.\n","lang":"de","translated":true,"requested_lang":"de","content_markdown":"\n# SSH-Zugriff über einen Proxy\n\nAgents müssen Befehle auf Remote-Maschinen ausführen — einen Container\ndeployen, ein Log lesen, eine Config reparieren. Rohe SSH-Private-Keys an\nein LLM zu übergeben ist eine schlechte Idee: Keys landen in\nKontextfenstern, Logs und Transkripten. Ein SSH-Proxy löst das: er besitzt\ndie Zugangsdaten, der Agent spricht nur HTTP.\n\n## Das Modell\n\n```\nLLM ──HTTPS──► SSH-Proxy ──SSH──► Ziel-Maschinen\n (besitzt Keys,\n Audit-Log,\n Rate-Limits)\n```\n\nDer Proxy stellt persistente Sessions mit einer einfachen REST-Oberfläche\nbereit:\n\n| Endpoint | Zweck |\n|---|---|\n| `POST /connect?target=vps1` | Session öffnen → `session_id` |\n| `POST //exec` `{command, timeout}` | Befehl ausführen (async) → `exec_id` |\n| `GET //exec/` | auf Ausgabe pollen |\n| SFTP-Endpoints | Datei-Up-/Download, `ls`, `mkdir`, `rm` |\n\nDie Auth ist ein Bearer-Token — dasselbe Muster wie bei jeder anderen API,\ndie du nutzt.\n\n## Das Ausführungsmuster\n\n```bash\n# 1. Einmal verbinden, die Session für die ganze Task wiederverwenden\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. Befehl ausführen\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. Ergebnis abholen\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Spielregeln\n\n1. **Sessions wiederverwenden.** Eine Verbindung pro Befehl verschwendet\n Ressourcen und rattert gegen Rate-Limits. Speichere die `session_id`\n (z.B. `/tmp/vps1_sid`) und mache vorher einen Heartbeat.\n2. **Targets benennen statt sie zu suchen.** Targets sind vorregistriert\n (`vps1`, `pi`, …). Der Proxy ist die einzige Wahrheitsquelle — nie IPs\n in Agent-Code hardcoden.\n3. **Für Dateien SFTP statt shell-cat/heredoc.** Binärdaten über `exec` zu\n schicken korrumpiert die Nutzdaten. Nutze die dedizierten Upload-/Download-\n Endpoints.\n4. **Befehle sauber quoten.** Der JSON-Body wird zweimal geparst (HTTP +\n Shell). Umschließe Remote-Befehle mit einfachen Anführungszeichen und\n halte sie einzeilig.\n5. **Von Auditing ausgehen.** Jeder exec landet im Audit-Log des Proxies —\n verhalte dich so, als würde der Mensch alles lesen (er kann).\n\n## Wann exec NICHT nutzen\n\n- Strukturierten Zustand lesen, der eine API hat (Docker, Datenbanken, die\n Synapse-Mind-API) — immer die API vor CLI-Output-Parsing bevorzugen.\n- Lange laufende interaktive Prozesse. `exec` ist fire-and-forget mit\n Timeout; nutze `nohup` + Statusdatei auf dem Ziel.\n- Alles Destruktive ohne explizite Anweisung. Der Proxy gibt dir die\n Macht — der Mensch gibt dir die Erlaubnis.\n\n## Fehlerbehandlung\n\n| Symptom | Lösung |\n|---|---|\n| 401 beim Verbinden | Token abgelaufen — neu aus Memory/Settings lesen, nie aus einem Transkript |\n| Session 404 | Session abgelaufen (24h Cap) — neu verbinden |\n| exec-Timeout | `timeout` erhöhen oder Befehl splitten; Last auf dem Ziel prüfen |\n| Verstümmelte Dateiinhalte | du hast `exec` statt SFTP genutzt — auf die SFTP-Endpoints wechseln |\n","content_html":"

SSH-Zugriff über einen Proxy

\n

Agents müssen Befehle auf Remote-Maschinen ausführen — einen Container\ndeployen, ein Log lesen, eine Config reparieren. Rohe SSH-Private-Keys an\nein LLM zu übergeben ist eine schlechte Idee: Keys landen in\nKontextfenstern, Logs und Transkripten. Ein SSH-Proxy löst das: er besitzt\ndie Zugangsdaten, der Agent spricht nur HTTP.

\n

Das Modell

\n
LLM ──HTTPS──► SSH-Proxy ──SSH──► Ziel-Maschinen\n               (besitzt Keys,\n                Audit-Log,\n                Rate-Limits)

Der Proxy stellt persistente Sessions mit einer einfachen REST-Oberfläche\nbereit:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointZweck
POST /connect?target=vps1Session öffnen → session_id
POST /<sid>/exec {command, timeout}Befehl ausführen (async) → exec_id
GET /<sid>/exec/<exec_id>auf Ausgabe pollen
SFTP-EndpointsDatei-Up-/Download, ls, mkdir, rm
\n

Die Auth ist ein Bearer-Token — dasselbe Muster wie bei jeder anderen API,\ndie du nutzt.

\n

Das Ausführungsmuster

\n
# 1. Einmal verbinden, die Session für die ganze Task wiederverwenden\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. Befehl ausführen\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. Ergebnis abholen\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Spielregeln

\n
    \n
  1. Sessions wiederverwenden. Eine Verbindung pro Befehl verschwendet\nRessourcen und rattert gegen Rate-Limits. Speichere die session_id\n(z.B. /tmp/vps1_sid) und mache vorher einen Heartbeat.
    2. \n
  2. Targets benennen statt sie zu suchen. Targets sind vorregistriert\n(vps1, pi, …). Der Proxy ist die einzige Wahrheitsquelle — nie IPs\nin Agent-Code hardcoden.
    3. \n
  3. Für Dateien SFTP statt shell-cat/heredoc. Binärdaten über exec zu\nschicken korrumpiert die Nutzdaten. Nutze die dedizierten Upload-/Download-\nEndpoints.
    4. \n
  4. Befehle sauber quoten. Der JSON-Body wird zweimal geparst (HTTP +\nShell). Umschließe Remote-Befehle mit einfachen Anführungszeichen und\nhalte sie einzeilig.
    5. \n
  5. Von Auditing ausgehen. Jeder exec landet im Audit-Log des Proxies —\nverhalte dich so, als würde der Mensch alles lesen (er kann).
    6. \n
\n

Wann exec NICHT nutzen

\n
    \n
  • Strukturierten Zustand lesen, der eine API hat (Docker, Datenbanken, die\nSynapse-Mind-API) — immer die API vor CLI-Output-Parsing bevorzugen.
    • \n
  • Lange laufende interaktive Prozesse. exec ist fire-and-forget mit\nTimeout; nutze nohup + Statusdatei auf dem Ziel.
    • \n
  • Alles Destruktive ohne explizite Anweisung. Der Proxy gibt dir die\nMacht — der Mensch gibt dir die Erlaubnis.
    • \n
\n

Fehlerbehandlung

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SymptomLösung
401 beim VerbindenToken abgelaufen — neu aus Memory/Settings lesen, nie aus einem Transkript
Session 404Session abgelaufen (24h Cap) — neu verbinden
exec-Timeouttimeout erhöhen oder Befehl splitten; Last auf dem Ziel prüfen
Verstümmelte Dateiinhaltedu hast exec statt SFTP genutzt — auf die SFTP-Endpoints wechseln
\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","de"],"wordCount":348,"readMinutes":2,"llmContext":"NIEMALS rohe SSH-Private-Keys als LLM besitzen. Nutze eine SSH-Proxy-HTTP-API:\n1) POST /connect?target= → session_id (persistent, hält Stunden).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → Ausgabe, wenn fertig.\n4) Für Datei-Up-/Download die SFTP-Endpoints statt cat/heredoc nutzen.\nTargets sind vorregistrierte Namen (z.B. \"vps1\"), keine IPs — der Proxy ist\nder einzige Ort, an dem Zugangsdaten liegen.\n","requestedLang":"de","contentMarkdown":"\n# SSH-Zugriff über einen Proxy\n\nAgents müssen Befehle auf Remote-Maschinen ausführen — einen Container\ndeployen, ein Log lesen, eine Config reparieren. Rohe SSH-Private-Keys an\nein LLM zu übergeben ist eine schlechte Idee: Keys landen in\nKontextfenstern, Logs und Transkripten. Ein SSH-Proxy löst das: er besitzt\ndie Zugangsdaten, der Agent spricht nur HTTP.\n\n## Das Modell\n\n```\nLLM ──HTTPS──► SSH-Proxy ──SSH──► Ziel-Maschinen\n (besitzt Keys,\n Audit-Log,\n Rate-Limits)\n```\n\nDer Proxy stellt persistente Sessions mit einer einfachen REST-Oberfläche\nbereit:\n\n| Endpoint | Zweck |\n|---|---|\n| `POST /connect?target=vps1` | Session öffnen → `session_id` |\n| `POST //exec` `{command, timeout}` | Befehl ausführen (async) → `exec_id` |\n| `GET //exec/` | auf Ausgabe pollen |\n| SFTP-Endpoints | Datei-Up-/Download, `ls`, `mkdir`, `rm` |\n\nDie Auth ist ein Bearer-Token — dasselbe Muster wie bei jeder anderen API,\ndie du nutzt.\n\n## Das Ausführungsmuster\n\n```bash\n# 1. Einmal verbinden, die Session für die ganze Task wiederverwenden\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. Befehl ausführen\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. Ergebnis abholen\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Spielregeln\n\n1. **Sessions wiederverwenden.** Eine Verbindung pro Befehl verschwendet\n Ressourcen und rattert gegen Rate-Limits. Speichere die `session_id`\n (z.B. `/tmp/vps1_sid`) und mache vorher einen Heartbeat.\n2. **Targets benennen statt sie zu suchen.** Targets sind vorregistriert\n (`vps1`, `pi`, …). Der Proxy ist die einzige Wahrheitsquelle — nie IPs\n in Agent-Code hardcoden.\n3. **Für Dateien SFTP statt shell-cat/heredoc.** Binärdaten über `exec` zu\n schicken korrumpiert die Nutzdaten. Nutze die dedizierten Upload-/Download-\n Endpoints.\n4. **Befehle sauber quoten.** Der JSON-Body wird zweimal geparst (HTTP +\n Shell). Umschließe Remote-Befehle mit einfachen Anführungszeichen und\n halte sie einzeilig.\n5. **Von Auditing ausgehen.** Jeder exec landet im Audit-Log des Proxies —\n verhalte dich so, als würde der Mensch alles lesen (er kann).\n\n## Wann exec NICHT nutzen\n\n- Strukturierten Zustand lesen, der eine API hat (Docker, Datenbanken, die\n Synapse-Mind-API) — immer die API vor CLI-Output-Parsing bevorzugen.\n- Lange laufende interaktive Prozesse. `exec` ist fire-and-forget mit\n Timeout; nutze `nohup` + Statusdatei auf dem Ziel.\n- Alles Destruktive ohne explizite Anweisung. Der Proxy gibt dir die\n Macht — der Mensch gibt dir die Erlaubnis.\n\n## Fehlerbehandlung\n\n| Symptom | Lösung |\n|---|---|\n| 401 beim Verbinden | Token abgelaufen — neu aus Memory/Settings lesen, nie aus einem Transkript |\n| Session 404 | Session abgelaufen (24h Cap) — neu verbinden |\n| exec-Timeout | `timeout` erhöhen oder Befehl splitten; Last auf dem Ziel prüfen |\n| Verstümmelte Dateiinhalte | du hast `exec` statt SFTP genutzt — auf die SFTP-Endpoints wechseln |\n","contentHtml":"

SSH-Zugriff über einen Proxy

\n

Agents müssen Befehle auf Remote-Maschinen ausführen — einen Container\ndeployen, ein Log lesen, eine Config reparieren. Rohe SSH-Private-Keys an\nein LLM zu übergeben ist eine schlechte Idee: Keys landen in\nKontextfenstern, Logs und Transkripten. Ein SSH-Proxy löst das: er besitzt\ndie Zugangsdaten, der Agent spricht nur HTTP.

\n

Das Modell

\n
LLM ──HTTPS──► SSH-Proxy ──SSH──► Ziel-Maschinen\n               (besitzt Keys,\n                Audit-Log,\n                Rate-Limits)

Der Proxy stellt persistente Sessions mit einer einfachen REST-Oberfläche\nbereit:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointZweck
POST /connect?target=vps1Session öffnen → session_id
POST /<sid>/exec {command, timeout}Befehl ausführen (async) → exec_id
GET /<sid>/exec/<exec_id>auf Ausgabe pollen
SFTP-EndpointsDatei-Up-/Download, ls, mkdir, rm
\n

Die Auth ist ein Bearer-Token — dasselbe Muster wie bei jeder anderen API,\ndie du nutzt.

\n

Das Ausführungsmuster

\n
# 1. Einmal verbinden, die Session für die ganze Task wiederverwenden\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. Befehl ausführen\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. Ergebnis abholen\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Spielregeln

\n
    \n
  1. Sessions wiederverwenden. Eine Verbindung pro Befehl verschwendet\nRessourcen und rattert gegen Rate-Limits. Speichere die session_id\n(z.B. /tmp/vps1_sid) und mache vorher einen Heartbeat.
    2. \n
  2. Targets benennen statt sie zu suchen. Targets sind vorregistriert\n(vps1, pi, …). Der Proxy ist die einzige Wahrheitsquelle — nie IPs\nin Agent-Code hardcoden.
    3. \n
  3. Für Dateien SFTP statt shell-cat/heredoc. Binärdaten über exec zu\nschicken korrumpiert die Nutzdaten. Nutze die dedizierten Upload-/Download-\nEndpoints.
    4. \n
  4. Befehle sauber quoten. Der JSON-Body wird zweimal geparst (HTTP +\nShell). Umschließe Remote-Befehle mit einfachen Anführungszeichen und\nhalte sie einzeilig.
    5. \n
  5. Von Auditing ausgehen. Jeder exec landet im Audit-Log des Proxies —\nverhalte dich so, als würde der Mensch alles lesen (er kann).
    6. \n
\n

Wann exec NICHT nutzen

\n
    \n
  • Strukturierten Zustand lesen, der eine API hat (Docker, Datenbanken, die\nSynapse-Mind-API) — immer die API vor CLI-Output-Parsing bevorzugen.
    • \n
  • Lange laufende interaktive Prozesse. exec ist fire-and-forget mit\nTimeout; nutze nohup + Statusdatei auf dem Ziel.
    • \n
  • Alles Destruktive ohne explizite Anweisung. Der Proxy gibt dir die\nMacht — der Mensch gibt dir die Erlaubnis.
    • \n
\n

Fehlerbehandlung

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SymptomLösung
401 beim VerbindenToken abgelaufen — neu aus Memory/Settings lesen, nie aus einem Transkript
Session 404Session abgelaufen (24h Cap) — neu verbinden
exec-Timeouttimeout erhöhen oder Befehl splitten; Last auf dem Ziel prüfen
Verstümmelte Dateiinhaltedu hast exec statt SFTP genutzt — auf die SFTP-Endpoints wechseln
\n","translationsAvailable":["en","de"]}