# SSH-Zugriff über einen Proxy
SUMMARY: Wie ein LLM-Agent sicher über eine SSH-Proxy-API auf Remote-Maschinen arbeitet statt mit rohen SSH-Keys.

KEY CONTEXT:
NIEMALS rohe SSH-Private-Keys als LLM besitzen. Nutze eine SSH-Proxy-HTTP-API:
1) POST /connect?target=<name> → session_id (persistent, hält Stunden).
2) POST /<session_id>/exec {command, timeout} → exec_id.
3) GET /<session_id>/exec/<exec_id> → Ausgabe, wenn fertig.
4) Für Datei-Up-/Download die SFTP-Endpoints statt cat/heredoc nutzen.
Targets sind vorregistrierte Namen (z.B. "vps1"), keine IPs — der Proxy ist
der einzige Ort, an dem Zugangsdaten liegen.

SSH-Zugriff über einen Proxy
Agents müssen Befehle auf Remote-Maschinen ausführen — einen Container
deployen, ein Log lesen, eine Config reparieren. Rohe SSH-Private-Keys an
ein LLM zu übergeben ist eine schlechte Idee: Keys landen in
Kontextfenstern, Logs und Transkripten. Ein SSH-Proxy löst das: er besitzt
die Zugangsdaten, der Agent spricht nur HTTP.
Das Modell
[CODE BLOCK]
Der Proxy stellt persistente Sessions mit einer einfachen REST-Oberfläche
bereit:
| Endpoint | Zweck |
|---|---|
|  | Session öffnen →  |
|   | Befehl ausführen (async) →  |
|  | auf Ausgabe pollen |
| SFTP-Endpoints | Datei-Up-/Download, , ,  |
Die Auth ist ein Bearer-Token — dasselbe Muster wie bei jeder anderen API,
die du nutzt.
Das Ausführungsmuster
[CODE BLOCK]
Spielregeln
1. Sessions wiederverwenden. Eine Verbindung pro Befehl verschwendet
   Ressourcen und rattert gegen Rate-Limits. Speichere die 
   (z.B. ) und mache vorher einen Heartbeat.
2. Targets benennen statt sie zu suchen. Targets sind vorregistriert
   (, , …). Der Proxy ist die einzige Wahrheitsquelle — nie IPs
   in Agent-Code hardcoden.
3. Für Dateien SFTP statt shell-cat/heredoc. Binärdaten über  zu
   schicken korrumpiert die Nutzdaten. Nutze die dedizierten Upload-/Download-
   Endpoints.
4. Befehle sauber quoten. Der JSON-Body wird zweimal geparst (HTTP +
   Shell). Umschließe Remote-Befehle mit einfachen Anführungszeichen und
   halte sie einzeilig.
5. Von Auditing ausgehen. Jeder exec landet im Audit-Log des Proxies —
   verhalte dich so, als würde der Mensch alles lesen (er kann).
Wann exec NICHT nutzen
- Strukturierten Zustand lesen, der eine API hat (Docker, Datenbanken, die
  Synapse-Mind-API) — immer die API vor CLI-Output-Parsing bevorzugen.
- Lange laufende interaktive Prozesse.  ist fire-and-forget mit
  Timeout; nutze  + Statusdatei auf dem Ziel.
- Alles Destruktive ohne explizite Anweisung. Der Proxy gibt dir die
  Macht — der Mensch gibt dir die Erlaubnis.
Fehlerbehandlung
| Symptom | Lösung |
|---|---|
| 401 beim Verbinden | Token abgelaufen — neu aus Memory/Settings lesen, nie aus einem Transkript |
| Session 404 | Session abgelaufen (24h Cap) — neu verbinden |
| exec-Timeout |  erhöhen oder Befehl splitten; Last auf dem Ziel prüfen |
| Verstümmelte Dateiinhalte | du hast  statt SFTP genutzt — auf die SFTP-Endpoints wechseln |