# Proxy üzerinden SSH erişimi

Ajanların uzak makinelerde komut çalıştırması gerekir — bir konteyner dağıtmak, bir log okumak, bir config düzeltmek. Ham SSH özel anahtarlarını bir LLM'e vermek kötü bir fikirdir: anahtarlar bağlam pencerelerine, loglara ve kayıtlara düşer. Bir SSH-proxy bunu çözer: kimlik bilgilerini o tutar, ajan yalnızca HTTP konuşur.

## Model

```
LLM ──HTTPS──► SSH-proxy ──SSH──► hedef makineler
                (anahtarları tutar,
                 denetim günlüğü,
                 hız limitleri)
```

Proxy, basit bir REST yüzeyi ile kalıcı oturumlar sunar:

| Uç | Amaç |
|---|---|
| `POST /connect?target=vps1` | bir oturum aç → `session_id` |
| `POST /<sid>/exec` `{command, timeout}` | komut çalıştır (async) → `exec_id` |
| `GET /<sid>/exec/<exec_id>` | çıktıyı sorgula |
| SFTP uçları | dosya yükleme/indirme, `ls`, `mkdir`, `rm` |

Kimlik doğrulama bir Bearer token'dır — kullandığın diğer her API ile aynı desen.

## Yürütme deseni

```bash
# 1. bir kez bağlan, oturumu tüm görev boyunca yeniden kullan
SID=$(curl -s -H "Authorization: Bearer $KEY" \
  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)

# 2. bir komut çalıştır
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. sonucu sorgula
curl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"
```

## Kurallar

1. **Oturumları yeniden kullan.** Her komut için bağlanmak kaynak harcar ve hız limitlerini tetikler. `session_id`'yi sakla (örn. `/tmp/vps1_sid`) ve yeniden kullanmadan önce heartbeat ile kontrol et.
2. **Hedefleri adlandır, keşfetme.** Hedefler önceden kayıtlıdır (`vps1`, `pi`, …). Proxy tek doğruluk kaynağıdır — ajan koduna asla IP adresi gömme.
3. **Dosyalar için shell cat/heredoc yerine SFTP'yi tercih et.** `exec` üzerinden ikili veri escape etmek yükleri bozar. Özel yükleme/indirme uçlarını kullan.
4. **Komutlarını tırnakla.** JSON gövdesi iki kez parse edilir (HTTP + shell). Uzak komutları tek tırnak içine al ve tek satırda tut.
5. **Denetim olduğunu varsay.** Her exec proxy'nin denetim günlüğüne düşer — insan her şeyi okuyormuş gibi davran (okuyabilir).

## exec NE ZAMAN kullanılmaz

- Bir API'si olan yapılandırılmış durumu okumak (Docker, veritabanları, Synapse Mind API) — CLI çıktısı ayrıştırmak yerine her zaman API'yi tercih et.
- Uzun süren etkileşimli süreçler. `exec`, zaman aşımlı fire-and-forget'tır; bunun yerine hedefte `nohup` + bir durum dosyası kullan.
- Açık talimat olmadan yıkıcı herhangi bir şey. Proxy sana gücü verir — insan sana izni verir.

## Hata kurtarma

| Belirti | Çözüm |
|---|---|
| connect'te 401 | token süresi doldu — memory/settings'ten yeniden oku, asla bir kayıttan değil |
| oturum 404 | oturum süresi doldu (24h sınırı) — yeniden bağlan |
| exec zaman aşımı | `timeout` değerini yükselt ya da komutu böl; hedefin yükünü kontrol et |
| bozuk dosya içeriği | SFTP yerine `exec` kullandın — SFTP uçlarına geç |