{"title":"Akses SSH melalui proxy","slug":"ssh-proxy-access","category":"llm-cookbook","summary":"Bagaimana agen LLM menjalankan perintah di mesin jarak jauh dengan aman melalui API proxy SSH alih-alih kunci SSH mentah.","audience":["llm"],"tags":["cookbook","ssh","proxy","infrastructure","remote-execution"],"difficulty":"intermediate","updated":"2026-09-26","word_count":340,"read_minutes":2,"llm_context":"JANGAN PERNAH menyimpan kunci privat SSH mentah sebagai LLM. Gunakan HTTP API proxy SSH:\n1) POST /connect?target= → session_id (persisten, bertahan berjam-jam).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → keluaran saat selesai.\n4) Gunakan endpoint SFTP untuk unggah/unduh berkas alih-alih cat/heredoc.\nTarget adalah nama yang didaftarkan lebih dulu (mis. \"vps1\"), bukan IP — proxy\nadalah satu-satunya tempat kredensial hidup.\n","lang":"id","translated":true,"requested_lang":"id","content_markdown":"\n# Akses SSH melalui proxy\n\nAgen 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.\n\n## Modelnya\n\n```\nLLM ──HTTPS──► Proxy SSH ──SSH──► mesin target\n (memegang kunci,\n log audit,\n batas laju)\n```\n\nProxy memaparkan sesi persisten dengan permukaan REST sederhana:\n\n| Endpoint | Tujuan |\n|---|---|\n| `POST /connect?target=vps1` | membuka sesi → `session_id` |\n| `POST //exec` `{command, timeout}` | menjalankan perintah (async) → `exec_id` |\n| `GET //exec/` | polling keluaran |\n| Endpoint SFTP | unggah/unduh berkas, `ls`, `mkdir`, `rm` |\n\nAutentikasi berupa token Bearer — pola yang sama seperti semua API lain yang kamu pakai.\n\n## Pola eksekusi\n\n```bash\n# 1. sambungkan sekali, pakai ulang sesi untuk seluruh tugas\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. jalankan perintah\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. polling hasilnya\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Aturan main\n\n1. **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.\n2. **Namai target, jangan menemukannya.** Target terdaftar lebih dulu (`vps1`, `pi`, …). Proxy adalah satu-satunya sumber kebenaran — jangan pernah hardcode alamat IP di kode agen.\n3. **Utamakan SFTP daripada cat/heredoc shell untuk berkas.** Meloloskan data biner lewat `exec` merusak payload. Gunakan endpoint unggah/unduh khusus.\n4. **Kutip perintahmu.** Badan JSON diurai dua kali (HTTP + shell). Bungkus perintah jarak jauh dalam tanda kutip tunggal dan jaga satu baris.\n5. **Asumsikan audit.** Setiap exec masuk log audit proxy — bersikaplah seolah manusia membaca segalanya (ia bisa).\n\n## Kapan exec TIDAK dipakai\n\n- Membaca keadaan terstruktur yang punya API (Docker, basis data, Mind API Synapse) — selalu utamakan API daripada mengurai keluaran CLI.\n- Proses interaktif berdurasi panjang. `exec` fire-and-forget dengan batas waktu; pakai `nohup` + berkas status di target sebagai gantinya.\n- Apa pun yang merusak tanpa instruksi eksplisit. Proxy memberimu kekuatan — manusia memberimu izin.\n\n## Pemulihan kesalahan\n\n| Gejala | Solusi |\n|---|---|\n| 401 saat connect | token kedaluwarsa — baca ulang dari memory/settings, tidak pernah dari transkrip |\n| sesi 404 | sesi kedaluwarsa (batas 24 jam) — sambung ulang |\n| exec timeout | naikkan `timeout` atau pecah perintahnya; cek beban target |\n| isi berkas rusak | kamu memakai `exec` alih-alih SFTP — pindah ke endpoint SFTP |\n","content_html":"

Akses SSH melalui proxy

\n

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.

\n

Modelnya

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

Proxy memaparkan sesi persisten dengan permukaan REST sederhana:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointTujuan
POST /connect?target=vps1membuka sesi → session_id
POST /<sid>/exec {command, timeout}menjalankan perintah (async) → exec_id
GET /<sid>/exec/<exec_id>polling keluaran
Endpoint SFTPunggah/unduh berkas, ls, mkdir, rm
\n

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

\n

Pola eksekusi

\n
# 1. sambungkan sekali, pakai ulang sesi untuk seluruh tugas\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. jalankan perintah\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. polling hasilnya\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Aturan main

\n
    \n
  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. \n
  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. \n
  3. Utamakan SFTP daripada cat/heredoc shell untuk berkas. Meloloskan data biner lewat exec merusak payload. Gunakan endpoint unggah/unduh khusus.
    4. \n
  4. Kutip perintahmu. Badan JSON diurai dua kali (HTTP + shell). Bungkus perintah jarak jauh dalam tanda kutip tunggal dan jaga satu baris.
    5. \n
  5. Asumsikan audit. Setiap exec masuk log audit proxy — bersikaplah seolah manusia membaca segalanya (ia bisa).
    6. \n
\n

Kapan exec TIDAK dipakai

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

Pemulihan kesalahan

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
GejalaSolusi
401 saat connecttoken kedaluwarsa — baca ulang dari memory/settings, tidak pernah dari transkrip
sesi 404sesi kedaluwarsa (batas 24 jam) — sambung ulang
exec timeoutnaikkan timeout atau pecah perintahnya; cek beban target
isi berkas rusakkamu memakai exec alih-alih SFTP — pindah ke endpoint SFTP
\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","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"],"wordCount":340,"readMinutes":2,"llmContext":"JANGAN PERNAH menyimpan kunci privat SSH mentah sebagai LLM. Gunakan HTTP API proxy SSH:\n1) POST /connect?target= → session_id (persisten, bertahan berjam-jam).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → keluaran saat selesai.\n4) Gunakan endpoint SFTP untuk unggah/unduh berkas alih-alih cat/heredoc.\nTarget adalah nama yang didaftarkan lebih dulu (mis. \"vps1\"), bukan IP — proxy\nadalah satu-satunya tempat kredensial hidup.\n","requestedLang":"id","contentMarkdown":"\n# Akses SSH melalui proxy\n\nAgen 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.\n\n## Modelnya\n\n```\nLLM ──HTTPS──► Proxy SSH ──SSH──► mesin target\n (memegang kunci,\n log audit,\n batas laju)\n```\n\nProxy memaparkan sesi persisten dengan permukaan REST sederhana:\n\n| Endpoint | Tujuan |\n|---|---|\n| `POST /connect?target=vps1` | membuka sesi → `session_id` |\n| `POST //exec` `{command, timeout}` | menjalankan perintah (async) → `exec_id` |\n| `GET //exec/` | polling keluaran |\n| Endpoint SFTP | unggah/unduh berkas, `ls`, `mkdir`, `rm` |\n\nAutentikasi berupa token Bearer — pola yang sama seperti semua API lain yang kamu pakai.\n\n## Pola eksekusi\n\n```bash\n# 1. sambungkan sekali, pakai ulang sesi untuk seluruh tugas\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. jalankan perintah\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. polling hasilnya\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Aturan main\n\n1. **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.\n2. **Namai target, jangan menemukannya.** Target terdaftar lebih dulu (`vps1`, `pi`, …). Proxy adalah satu-satunya sumber kebenaran — jangan pernah hardcode alamat IP di kode agen.\n3. **Utamakan SFTP daripada cat/heredoc shell untuk berkas.** Meloloskan data biner lewat `exec` merusak payload. Gunakan endpoint unggah/unduh khusus.\n4. **Kutip perintahmu.** Badan JSON diurai dua kali (HTTP + shell). Bungkus perintah jarak jauh dalam tanda kutip tunggal dan jaga satu baris.\n5. **Asumsikan audit.** Setiap exec masuk log audit proxy — bersikaplah seolah manusia membaca segalanya (ia bisa).\n\n## Kapan exec TIDAK dipakai\n\n- Membaca keadaan terstruktur yang punya API (Docker, basis data, Mind API Synapse) — selalu utamakan API daripada mengurai keluaran CLI.\n- Proses interaktif berdurasi panjang. `exec` fire-and-forget dengan batas waktu; pakai `nohup` + berkas status di target sebagai gantinya.\n- Apa pun yang merusak tanpa instruksi eksplisit. Proxy memberimu kekuatan — manusia memberimu izin.\n\n## Pemulihan kesalahan\n\n| Gejala | Solusi |\n|---|---|\n| 401 saat connect | token kedaluwarsa — baca ulang dari memory/settings, tidak pernah dari transkrip |\n| sesi 404 | sesi kedaluwarsa (batas 24 jam) — sambung ulang |\n| exec timeout | naikkan `timeout` atau pecah perintahnya; cek beban target |\n| isi berkas rusak | kamu memakai `exec` alih-alih SFTP — pindah ke endpoint SFTP |\n","contentHtml":"

Akses SSH melalui proxy

\n

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.

\n

Modelnya

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

Proxy memaparkan sesi persisten dengan permukaan REST sederhana:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointTujuan
POST /connect?target=vps1membuka sesi → session_id
POST /<sid>/exec {command, timeout}menjalankan perintah (async) → exec_id
GET /<sid>/exec/<exec_id>polling keluaran
Endpoint SFTPunggah/unduh berkas, ls, mkdir, rm
\n

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

\n

Pola eksekusi

\n
# 1. sambungkan sekali, pakai ulang sesi untuk seluruh tugas\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. jalankan perintah\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. polling hasilnya\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Aturan main

\n
    \n
  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. \n
  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. \n
  3. Utamakan SFTP daripada cat/heredoc shell untuk berkas. Meloloskan data biner lewat exec merusak payload. Gunakan endpoint unggah/unduh khusus.
    4. \n
  4. Kutip perintahmu. Badan JSON diurai dua kali (HTTP + shell). Bungkus perintah jarak jauh dalam tanda kutip tunggal dan jaga satu baris.
    5. \n
  5. Asumsikan audit. Setiap exec masuk log audit proxy — bersikaplah seolah manusia membaca segalanya (ia bisa).
    6. \n
\n

Kapan exec TIDAK dipakai

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

Pemulihan kesalahan

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
GejalaSolusi
401 saat connecttoken kedaluwarsa — baca ulang dari memory/settings, tidak pernah dari transkrip
sesi 404sesi kedaluwarsa (batas 24 jam) — sambung ulang
exec timeoutnaikkan timeout atau pecah perintahnya; cek beban target
isi berkas rusakkamu memakai exec alih-alih SFTP — pindah ke endpoint SFTP
\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}