# Dostęp SSH przez proxy

Agenty muszą wykonywać polecenia na zdalnych maszynach — wdrażać kontener, czytać log, naprawiać konfigurację. Oddawanie surowych kluczy prywatnych SSH LLM to zły pomysł: klucze trafiają do okien kontekstu, logów i transkrypcji. Proxy SSH rozwiązuje to: to on posiada dane uwierzytelniające, agent mówi tylko HTTP.

## Model

```
LLM ──HTTPS──► Proxy SSH ──SSH──► maszyny docelowe
                (posiada klucze,
                 dziennik audytu,
                 limity zapytań)
```

Proxy udostępnia trwałe sesje przez prostą powierzchnię REST:

| Endpoint | Cel |
|---|---|
| `POST /connect?target=vps1` | otwarcie sesji → `session_id` |
| `POST /<sid>/exec` `{command, timeout}` | wykonanie polecenia (async) → `exec_id` |
| `GET /<sid>/exec/<exec_id>` | odpytanie o wyjście |
| Endpointy SFTP | wysyłanie/pobieranie plików, `ls`, `mkdir`, `rm` |

Uwierzytelnianie to token Bearer — ten sam wzorzec, co w każdej innej API, którą używasz.

## Wzorzec wykonania

```bash
# 1. połącz raz, używaj sesji przez całe zadanie
SID=$(curl -s -H "Authorization: Bearer $KEY" \
  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)

# 2. wykonaj polecenie
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. odpytaj o wynik
curl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"
```

## Reguły postępowania

1. **Używaj sesji ponownie.** Łączenie na każde polecenie marnuje zasoby i uruchamia limity. Zapisz `session_id` (np. `/tmp/vps1_sid`) i daj mu heartbeat przed ponownym użyciem.
2. **Nazywaj cele, nie odkrywaj ich.** Cele są predefiniowane (`vps1`, `pi`, …). Proxy jest jedynym źródłem prawdy — nigdy nie zaszywaj adresów IP w kodzie agenta.
3. **Preferuj SFTP nad cat/heredoc shella dla plików.** Escapowanie danych binarnych przez `exec` psuje ładunki. Używaj dedykowanych endpointów wysyłania/pobierania.
4. **Cytuj swoje polecenia.** Treść JSON jest parsowana dwukrotnie (HTTP + shell). Owiń zdalne polecenia w pojedyncze cudzysłowy i trzymaj je w jednej linii.
5. **Zakładaj audyt.** Każdy exec trafia do dziennika audytu proxy — zachowuj się tak, jakby człowiek czytał wszystko (może).

## Kiedy NIE używać exec

- Czytanie ustrukturyzowanego stanu, który ma API (Docker, bazy danych, Mind API Synapse) — zawsze preferuj API nad parsowaniem wyjścia CLI.
- Długotrwałe procesy interaktywne. `exec` to fire-and-forget z timeoutem; użyj `nohup` + pliku statusu na celu.
- Cokolwiek destrukcyjnego bez wyraźnego polecenia. Proxy daje ci moc — człowiek daje ci pozwolenie.

## Odzyskiwanie po błędach

| Objaw | Rozwiązanie |
|---|---|
| 401 przy connect | token wygasł — odczytaj go ponownie z memory/settings, nigdy z transkrypcji |
| sesja 404 | sesja wygasła (limit 24h) — połącz ponownie |
| timeout exec | zwiększ `timeout` albo podziel polecenie; sprawdź obciążenie celu |
| zepsuta zawartość pliku | użyłeś `exec` zamiast SFTP — przejdź na endpointy SFTP |