# Akses SSH melalui proxy

Agen perlu menjalankan perintah di mesin jarak jauh — deploy kontainer, membaca log, memperbaiki config. Menyerahkan kunci privat SSH mentah kepada LLM adalah ide buruk: kunci berakhir di jendela konteks, log, dan transkrip. Proxy SSH menyelesaikannya: kredensial dipegangnya, agen hanya berbicara HTTP.

## Modelnya

```
LLM ──HTTPS──► Proxy SSH ──SSH──► mesin target
                (memegang kunci,
                 log audit,
                 batas laju)
```

Proxy memaparkan sesi persisten dengan permukaan REST sederhana:

| Endpoint | Tujuan |
|---|---|
| `POST /connect?target=vps1` | membuka sesi → `session_id` |
| `POST /<sid>/exec` `{command, timeout}` | menjalankan perintah (async) → `exec_id` |
| `GET /<sid>/exec/<exec_id>` | polling keluaran |
| Endpoint SFTP | unggah/unduh berkas, `ls`, `mkdir`, `rm` |

Autentikasi berupa token Bearer — pola yang sama seperti semua API lain yang kamu pakai.

## Pola eksekusi

```bash
# 1. sambungkan sekali, pakai ulang sesi untuk seluruh tugas
SID=$(curl -s -H "Authorization: Bearer $KEY" \
  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)

# 2. jalankan perintah
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. polling hasilnya
curl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"
```

## Aturan main

1. **Pakai ulang sesi.** Menyambung per perintah memboroskan sumber daya dan memicu batas laju. Simpan `session_id` (mis. `/tmp/vps1_sid`) dan kirimkan heartbeat sebelum pakai ulang.
2. **Namai target, jangan menemukannya.** Target terdaftar lebih dulu (`vps1`, `pi`, …). Proxy adalah satu-satunya sumber kebenaran — jangan pernah hardcode alamat IP di kode agen.
3. **Utamakan SFTP daripada cat/heredoc shell untuk berkas.** Meloloskan data biner lewat `exec` merusak payload. Gunakan endpoint unggah/unduh khusus.
4. **Kutip perintahmu.** Badan JSON diurai dua kali (HTTP + shell). Bungkus perintah jarak jauh dalam tanda kutip tunggal dan jaga satu baris.
5. **Asumsikan audit.** Setiap exec masuk log audit proxy — bersikaplah seolah manusia membaca segalanya (ia bisa).

## Kapan exec TIDAK dipakai

- Membaca keadaan terstruktur yang punya API (Docker, basis data, Mind API Synapse) — selalu utamakan API daripada mengurai keluaran CLI.
- Proses interaktif berdurasi panjang. `exec` fire-and-forget dengan batas waktu; pakai `nohup` + berkas status di target sebagai gantinya.
- Apa pun yang merusak tanpa instruksi eksplisit. Proxy memberimu kekuatan — manusia memberimu izin.

## Pemulihan kesalahan

| Gejala | Solusi |
|---|---|
| 401 saat connect | token kedaluwarsa — baca ulang dari memory/settings, tidak pernah dari transkrip |
| sesi 404 | sesi kedaluwarsa (batas 24 jam) — sambung ulang |
| exec timeout | naikkan `timeout` atau pecah perintahnya; cek beban target |
| isi berkas rusak | kamu memakai `exec` alih-alih SFTP — pindah ke endpoint SFTP |