{"title":"Dostęp SSH przez proxy","slug":"ssh-proxy-access","category":"llm-cookbook","summary":"Jak agent LLM bezpiecznie wykonuje polecenia na zdalnych maszynach przez API proxy SSH zamiast surowych kluczy SSH.","audience":["llm"],"tags":["cookbook","ssh","proxy","infrastructure","remote-execution"],"difficulty":"intermediate","updated":"2026-09-26","word_count":342,"read_minutes":2,"llm_context":"NIGDY nie trzymaj surowych kluczy prywatnych SSH jako LLM. Używaj HTTP-API proxy SSH:\n1) POST /connect?target= → session_id (trwałe, przeżywa godziny).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → wyjście po zakończeniu.\n4) Do wysyłania/pobierania plików używaj endpointów SFTP zamiast cat/heredoc.\nCele to predefiniowane nazwy (np. \"vps1\"), nie IP — proxy jest jedynym miejscem,\ngdzie żyją dane uwierzytelniające.\n","lang":"pl","translated":true,"requested_lang":"pl","content_markdown":"\n# Dostęp SSH przez proxy\n\nAgenty 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.\n\n## Model\n\n```\nLLM ──HTTPS──► Proxy SSH ──SSH──► maszyny docelowe\n (posiada klucze,\n dziennik audytu,\n limity zapytań)\n```\n\nProxy udostępnia trwałe sesje przez prostą powierzchnię REST:\n\n| Endpoint | Cel |\n|---|---|\n| `POST /connect?target=vps1` | otwarcie sesji → `session_id` |\n| `POST //exec` `{command, timeout}` | wykonanie polecenia (async) → `exec_id` |\n| `GET //exec/` | odpytanie o wyjście |\n| Endpointy SFTP | wysyłanie/pobieranie plików, `ls`, `mkdir`, `rm` |\n\nUwierzytelnianie to token Bearer — ten sam wzorzec, co w każdej innej API, którą używasz.\n\n## Wzorzec wykonania\n\n```bash\n# 1. połącz raz, używaj sesji przez całe zadanie\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. wykonaj polecenie\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. odpytaj o wynik\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Reguły postępowania\n\n1. **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.\n2. **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.\n3. **Preferuj SFTP nad cat/heredoc shella dla plików.** Escapowanie danych binarnych przez `exec` psuje ładunki. Używaj dedykowanych endpointów wysyłania/pobierania.\n4. **Cytuj swoje polecenia.** Treść JSON jest parsowana dwukrotnie (HTTP + shell). Owiń zdalne polecenia w pojedyncze cudzysłowy i trzymaj je w jednej linii.\n5. **Zakładaj audyt.** Każdy exec trafia do dziennika audytu proxy — zachowuj się tak, jakby człowiek czytał wszystko (może).\n\n## Kiedy NIE używać exec\n\n- Czytanie ustrukturyzowanego stanu, który ma API (Docker, bazy danych, Mind API Synapse) — zawsze preferuj API nad parsowaniem wyjścia CLI.\n- Długotrwałe procesy interaktywne. `exec` to fire-and-forget z timeoutem; użyj `nohup` + pliku statusu na celu.\n- Cokolwiek destrukcyjnego bez wyraźnego polecenia. Proxy daje ci moc — człowiek daje ci pozwolenie.\n\n## Odzyskiwanie po błędach\n\n| Objaw | Rozwiązanie |\n|---|---|\n| 401 przy connect | token wygasł — odczytaj go ponownie z memory/settings, nigdy z transkrypcji |\n| sesja 404 | sesja wygasła (limit 24h) — połącz ponownie |\n| timeout exec | zwiększ `timeout` albo podziel polecenie; sprawdź obciążenie celu |\n| zepsuta zawartość pliku | użyłeś `exec` zamiast SFTP — przejdź na endpointy SFTP |\n","content_html":"

Dostęp SSH przez proxy

\n

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.

\n

Model

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

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointCel
POST /connect?target=vps1otwarcie sesji → session_id
POST /<sid>/exec {command, timeout}wykonanie polecenia (async) → exec_id
GET /<sid>/exec/<exec_id>odpytanie o wyjście
Endpointy SFTPwysyłanie/pobieranie plików, ls, mkdir, rm
\n

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

\n

Wzorzec wykonania

\n
# 1. połącz raz, używaj sesji przez całe zadanie\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. wykonaj polecenie\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. odpytaj o wynik\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Reguły postępowania

\n
    \n
  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. \n
  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. \n
  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. \n
  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. \n
  5. Zakładaj audyt. Każdy exec trafia do dziennika audytu proxy — zachowuj się tak, jakby człowiek czytał wszystko (może).
    6. \n
\n

Kiedy NIE używać exec

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

Odzyskiwanie po błędach

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ObjawRozwiązanie
401 przy connecttoken wygasł — odczytaj go ponownie z memory/settings, nigdy z transkrypcji
sesja 404sesja wygasła (limit 24h) — połącz ponownie
timeout execzwiększ timeout albo podziel polecenie; sprawdź obciążenie celu
zepsuta zawartość plikuużyłeś exec zamiast SFTP — przejdź na endpointy 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":342,"readMinutes":2,"llmContext":"NIGDY nie trzymaj surowych kluczy prywatnych SSH jako LLM. Używaj HTTP-API proxy SSH:\n1) POST /connect?target= → session_id (trwałe, przeżywa godziny).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → wyjście po zakończeniu.\n4) Do wysyłania/pobierania plików używaj endpointów SFTP zamiast cat/heredoc.\nCele to predefiniowane nazwy (np. \"vps1\"), nie IP — proxy jest jedynym miejscem,\ngdzie żyją dane uwierzytelniające.\n","requestedLang":"pl","contentMarkdown":"\n# Dostęp SSH przez proxy\n\nAgenty 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.\n\n## Model\n\n```\nLLM ──HTTPS──► Proxy SSH ──SSH──► maszyny docelowe\n (posiada klucze,\n dziennik audytu,\n limity zapytań)\n```\n\nProxy udostępnia trwałe sesje przez prostą powierzchnię REST:\n\n| Endpoint | Cel |\n|---|---|\n| `POST /connect?target=vps1` | otwarcie sesji → `session_id` |\n| `POST //exec` `{command, timeout}` | wykonanie polecenia (async) → `exec_id` |\n| `GET //exec/` | odpytanie o wyjście |\n| Endpointy SFTP | wysyłanie/pobieranie plików, `ls`, `mkdir`, `rm` |\n\nUwierzytelnianie to token Bearer — ten sam wzorzec, co w każdej innej API, którą używasz.\n\n## Wzorzec wykonania\n\n```bash\n# 1. połącz raz, używaj sesji przez całe zadanie\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. wykonaj polecenie\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. odpytaj o wynik\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Reguły postępowania\n\n1. **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.\n2. **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.\n3. **Preferuj SFTP nad cat/heredoc shella dla plików.** Escapowanie danych binarnych przez `exec` psuje ładunki. Używaj dedykowanych endpointów wysyłania/pobierania.\n4. **Cytuj swoje polecenia.** Treść JSON jest parsowana dwukrotnie (HTTP + shell). Owiń zdalne polecenia w pojedyncze cudzysłowy i trzymaj je w jednej linii.\n5. **Zakładaj audyt.** Każdy exec trafia do dziennika audytu proxy — zachowuj się tak, jakby człowiek czytał wszystko (może).\n\n## Kiedy NIE używać exec\n\n- Czytanie ustrukturyzowanego stanu, który ma API (Docker, bazy danych, Mind API Synapse) — zawsze preferuj API nad parsowaniem wyjścia CLI.\n- Długotrwałe procesy interaktywne. `exec` to fire-and-forget z timeoutem; użyj `nohup` + pliku statusu na celu.\n- Cokolwiek destrukcyjnego bez wyraźnego polecenia. Proxy daje ci moc — człowiek daje ci pozwolenie.\n\n## Odzyskiwanie po błędach\n\n| Objaw | Rozwiązanie |\n|---|---|\n| 401 przy connect | token wygasł — odczytaj go ponownie z memory/settings, nigdy z transkrypcji |\n| sesja 404 | sesja wygasła (limit 24h) — połącz ponownie |\n| timeout exec | zwiększ `timeout` albo podziel polecenie; sprawdź obciążenie celu |\n| zepsuta zawartość pliku | użyłeś `exec` zamiast SFTP — przejdź na endpointy SFTP |\n","contentHtml":"

Dostęp SSH przez proxy

\n

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.

\n

Model

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

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointCel
POST /connect?target=vps1otwarcie sesji → session_id
POST /<sid>/exec {command, timeout}wykonanie polecenia (async) → exec_id
GET /<sid>/exec/<exec_id>odpytanie o wyjście
Endpointy SFTPwysyłanie/pobieranie plików, ls, mkdir, rm
\n

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

\n

Wzorzec wykonania

\n
# 1. połącz raz, używaj sesji przez całe zadanie\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. wykonaj polecenie\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. odpytaj o wynik\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Reguły postępowania

\n
    \n
  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. \n
  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. \n
  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. \n
  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. \n
  5. Zakładaj audyt. Każdy exec trafia do dziennika audytu proxy — zachowuj się tak, jakby człowiek czytał wszystko (może).
    6. \n
\n

Kiedy NIE używać exec

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

Odzyskiwanie po błędach

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ObjawRozwiązanie
401 przy connecttoken wygasł — odczytaj go ponownie z memory/settings, nigdy z transkrypcji
sesja 404sesja wygasła (limit 24h) — połącz ponownie
timeout execzwiększ timeout albo podziel polecenie; sprawdź obciążenie celu
zepsuta zawartość plikuużyłeś exec zamiast SFTP — przejdź na endpointy SFTP
\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}