{"title":"Accesso SSH via proxy","slug":"ssh-proxy-access","category":"llm-cookbook","summary":"Come un agente LLM esegue comandi su macchine remote in sicurezza tramite un'API proxy SSH invece di chiavi SSH grezze.","audience":["llm"],"tags":["cookbook","ssh","proxy","infrastructure","remote-execution"],"difficulty":"intermediate","updated":"2026-09-26","word_count":390,"read_minutes":2,"llm_context":"NON tenere MAI chiavi private SSH grezze come LLM. Usa un'API HTTP proxy SSH:\n1) POST /connect?target= → session_id (persistente, sopravvive ore).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → output a fine esecuzione.\n4) Usa gli endpoint SFTP per up/download di file invece di cat/heredoc.\nI target sono nomi pre-registrati (es. \"vps1\"), non IP — il proxy è l'unico\nposto in cui vivono le credenziali.\n","lang":"it","translated":true,"requested_lang":"it","content_markdown":"\n# Accesso SSH via proxy\n\nGli agenti devono eseguire comandi su macchine remote — deployare un container, leggere un log, correggere una config. Consegnare chiavi private SSH grezze a un LLM è una cattiva idea: le chiavi finiscono in finestre di contesto, log e trascrizioni. Un proxy SSH risolve il problema: le credenziali le detiene lui, l'agente parla solo HTTP.\n\n## Il modello\n\n```\nLLM ──HTTPS──► Proxy SSH ──SSH──► macchine target\n (detiene le chiavi,\n audit log,\n limiti di rate)\n```\n\nIl proxy espone sessioni persistenti con una superficie REST semplice:\n\n| Endpoint | Scopo |\n|---|---|\n| `POST /connect?target=vps1` | aprire una sessione → `session_id` |\n| `POST //exec` `{command, timeout}` | eseguire un comando (async) → `exec_id` |\n| `GET //exec/` | interrogare l'output |\n| Endpoint SFTP | up/download di file, `ls`, `mkdir`, `rm` |\n\nL'autenticazione è un token Bearer — lo stesso schema di ogni altra API che usi.\n\n## Il pattern di esecuzione\n\n```bash\n# 1. connetti una volta, riusa la sessione per tutto il task\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. esegui un comando\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. interroga il risultato\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Regole di ingaggio\n\n1. **Riusa le sessioni.** Connettersi per ogni comando spreca risorse e fa scattare i limiti di rate. Salva il `session_id` (es. `/tmp/vps1_sid`) e fai heartbeat prima di riutilizzarlo.\n2. **Nomina i target, non scoprili.** I target sono pre-registrati (`vps1`, `pi`, …). Il proxy è la fonte unica di verità — non hardcodare mai indirizzi IP nel codice agente.\n3. **Preferisci SFTP a cat/heredoc di shell per i file.** L'escaping di dati binari via `exec` corrompe i payload. Usa gli endpoint dedicati di upload/download.\n4. **Virgoletta i comandi.** Il corpo JSON viene parsato due volte (HTTP + shell). Avvolgi i comandi remoti in apici singoli e tienili su una riga.\n5. **Assumi l'auditing.** Ogni exec finisce nell'audit log del proxy — comportati come se l'umano leggesse tutto (può farlo).\n\n## Quando NON usare exec\n\n- Leggere stato strutturato che ha una API (Docker, database, la Mind API di Synapse) — preferisci sempre la API al parsing dell'output CLI.\n- Processi interattivi di lunga durata. `exec` è fire-and-forget con timeout; usa `nohup` + un file di stato sul target.\n- Qualsiasi cosa distruttiva senza istruzione esplicita. Il proxy ti dà il potere — l'umano ti dà il permesso.\n\n## Recupero errori\n\n| Sintomo | Rimedio |\n|---|---|\n| 401 al connect | token scaduto — rileggilo da memory/settings, mai da una trascrizione |\n| sessione 404 | sessione scaduta (limite 24h) — riconnetti |\n| timeout dell'exec | alza `timeout` o spezza il comando; verifica il carico del target |\n| contenuto file corrotto | hai usato `exec` invece di SFTP — passa agli endpoint SFTP |\n","content_html":"

Accesso SSH via proxy

\n

Gli agenti devono eseguire comandi su macchine remote — deployare un container, leggere un log, correggere una config. Consegnare chiavi private SSH grezze a un LLM è una cattiva idea: le chiavi finiscono in finestre di contesto, log e trascrizioni. Un proxy SSH risolve il problema: le credenziali le detiene lui, l'agente parla solo HTTP.

\n

Il modello

\n
LLM ──HTTPS──► Proxy SSH ──SSH──► macchine target\n                (detiene le chiavi,\n                 audit log,\n                 limiti di rate)

Il proxy espone sessioni persistenti con una superficie REST semplice:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointScopo
POST /connect?target=vps1aprire una sessione → session_id
POST /<sid>/exec {command, timeout}eseguire un comando (async) → exec_id
GET /<sid>/exec/<exec_id>interrogare l'output
Endpoint SFTPup/download di file, ls, mkdir, rm
\n

L'autenticazione è un token Bearer — lo stesso schema di ogni altra API che usi.

\n

Il pattern di esecuzione

\n
# 1. connetti una volta, riusa la sessione per tutto il task\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. esegui un comando\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. interroga il risultato\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Regole di ingaggio

\n
    \n
  1. Riusa le sessioni. Connettersi per ogni comando spreca risorse e fa scattare i limiti di rate. Salva il session_id (es. /tmp/vps1_sid) e fai heartbeat prima di riutilizzarlo.
    2. \n
  2. Nomina i target, non scoprili. I target sono pre-registrati (vps1, pi, …). Il proxy è la fonte unica di verità — non hardcodare mai indirizzi IP nel codice agente.
    3. \n
  3. Preferisci SFTP a cat/heredoc di shell per i file. L'escaping di dati binari via exec corrompe i payload. Usa gli endpoint dedicati di upload/download.
    4. \n
  4. Virgoletta i comandi. Il corpo JSON viene parsato due volte (HTTP + shell). Avvolgi i comandi remoti in apici singoli e tienili su una riga.
    5. \n
  5. Assumi l'auditing. Ogni exec finisce nell'audit log del proxy — comportati come se l'umano leggesse tutto (può farlo).
    6. \n
\n

Quando NON usare exec

\n
    \n
  • Leggere stato strutturato che ha una API (Docker, database, la Mind API di Synapse) — preferisci sempre la API al parsing dell'output CLI.
    • \n
  • Processi interattivi di lunga durata. exec è fire-and-forget con timeout; usa nohup + un file di stato sul target.
    • \n
  • Qualsiasi cosa distruttiva senza istruzione esplicita. Il proxy ti dà il potere — l'umano ti dà il permesso.
    • \n
\n

Recupero errori

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SintomoRimedio
401 al connecttoken scaduto — rileggilo da memory/settings, mai da una trascrizione
sessione 404sessione scaduta (limite 24h) — riconnetti
timeout dell'execalza timeout o spezza il comando; verifica il carico del target
contenuto file corrottohai usato exec invece di SFTP — passa agli 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":390,"readMinutes":2,"llmContext":"NON tenere MAI chiavi private SSH grezze come LLM. Usa un'API HTTP proxy SSH:\n1) POST /connect?target= → session_id (persistente, sopravvive ore).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → output a fine esecuzione.\n4) Usa gli endpoint SFTP per up/download di file invece di cat/heredoc.\nI target sono nomi pre-registrati (es. \"vps1\"), non IP — il proxy è l'unico\nposto in cui vivono le credenziali.\n","requestedLang":"it","contentMarkdown":"\n# Accesso SSH via proxy\n\nGli agenti devono eseguire comandi su macchine remote — deployare un container, leggere un log, correggere una config. Consegnare chiavi private SSH grezze a un LLM è una cattiva idea: le chiavi finiscono in finestre di contesto, log e trascrizioni. Un proxy SSH risolve il problema: le credenziali le detiene lui, l'agente parla solo HTTP.\n\n## Il modello\n\n```\nLLM ──HTTPS──► Proxy SSH ──SSH──► macchine target\n (detiene le chiavi,\n audit log,\n limiti di rate)\n```\n\nIl proxy espone sessioni persistenti con una superficie REST semplice:\n\n| Endpoint | Scopo |\n|---|---|\n| `POST /connect?target=vps1` | aprire una sessione → `session_id` |\n| `POST //exec` `{command, timeout}` | eseguire un comando (async) → `exec_id` |\n| `GET //exec/` | interrogare l'output |\n| Endpoint SFTP | up/download di file, `ls`, `mkdir`, `rm` |\n\nL'autenticazione è un token Bearer — lo stesso schema di ogni altra API che usi.\n\n## Il pattern di esecuzione\n\n```bash\n# 1. connetti una volta, riusa la sessione per tutto il task\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. esegui un comando\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. interroga il risultato\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Regole di ingaggio\n\n1. **Riusa le sessioni.** Connettersi per ogni comando spreca risorse e fa scattare i limiti di rate. Salva il `session_id` (es. `/tmp/vps1_sid`) e fai heartbeat prima di riutilizzarlo.\n2. **Nomina i target, non scoprili.** I target sono pre-registrati (`vps1`, `pi`, …). Il proxy è la fonte unica di verità — non hardcodare mai indirizzi IP nel codice agente.\n3. **Preferisci SFTP a cat/heredoc di shell per i file.** L'escaping di dati binari via `exec` corrompe i payload. Usa gli endpoint dedicati di upload/download.\n4. **Virgoletta i comandi.** Il corpo JSON viene parsato due volte (HTTP + shell). Avvolgi i comandi remoti in apici singoli e tienili su una riga.\n5. **Assumi l'auditing.** Ogni exec finisce nell'audit log del proxy — comportati come se l'umano leggesse tutto (può farlo).\n\n## Quando NON usare exec\n\n- Leggere stato strutturato che ha una API (Docker, database, la Mind API di Synapse) — preferisci sempre la API al parsing dell'output CLI.\n- Processi interattivi di lunga durata. `exec` è fire-and-forget con timeout; usa `nohup` + un file di stato sul target.\n- Qualsiasi cosa distruttiva senza istruzione esplicita. Il proxy ti dà il potere — l'umano ti dà il permesso.\n\n## Recupero errori\n\n| Sintomo | Rimedio |\n|---|---|\n| 401 al connect | token scaduto — rileggilo da memory/settings, mai da una trascrizione |\n| sessione 404 | sessione scaduta (limite 24h) — riconnetti |\n| timeout dell'exec | alza `timeout` o spezza il comando; verifica il carico del target |\n| contenuto file corrotto | hai usato `exec` invece di SFTP — passa agli endpoint SFTP |\n","contentHtml":"

Accesso SSH via proxy

\n

Gli agenti devono eseguire comandi su macchine remote — deployare un container, leggere un log, correggere una config. Consegnare chiavi private SSH grezze a un LLM è una cattiva idea: le chiavi finiscono in finestre di contesto, log e trascrizioni. Un proxy SSH risolve il problema: le credenziali le detiene lui, l'agente parla solo HTTP.

\n

Il modello

\n
LLM ──HTTPS──► Proxy SSH ──SSH──► macchine target\n                (detiene le chiavi,\n                 audit log,\n                 limiti di rate)

Il proxy espone sessioni persistenti con una superficie REST semplice:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointScopo
POST /connect?target=vps1aprire una sessione → session_id
POST /<sid>/exec {command, timeout}eseguire un comando (async) → exec_id
GET /<sid>/exec/<exec_id>interrogare l'output
Endpoint SFTPup/download di file, ls, mkdir, rm
\n

L'autenticazione è un token Bearer — lo stesso schema di ogni altra API che usi.

\n

Il pattern di esecuzione

\n
# 1. connetti una volta, riusa la sessione per tutto il task\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. esegui un comando\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. interroga il risultato\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Regole di ingaggio

\n
    \n
  1. Riusa le sessioni. Connettersi per ogni comando spreca risorse e fa scattare i limiti di rate. Salva il session_id (es. /tmp/vps1_sid) e fai heartbeat prima di riutilizzarlo.
    2. \n
  2. Nomina i target, non scoprili. I target sono pre-registrati (vps1, pi, …). Il proxy è la fonte unica di verità — non hardcodare mai indirizzi IP nel codice agente.
    3. \n
  3. Preferisci SFTP a cat/heredoc di shell per i file. L'escaping di dati binari via exec corrompe i payload. Usa gli endpoint dedicati di upload/download.
    4. \n
  4. Virgoletta i comandi. Il corpo JSON viene parsato due volte (HTTP + shell). Avvolgi i comandi remoti in apici singoli e tienili su una riga.
    5. \n
  5. Assumi l'auditing. Ogni exec finisce nell'audit log del proxy — comportati come se l'umano leggesse tutto (può farlo).
    6. \n
\n

Quando NON usare exec

\n
    \n
  • Leggere stato strutturato che ha una API (Docker, database, la Mind API di Synapse) — preferisci sempre la API al parsing dell'output CLI.
    • \n
  • Processi interattivi di lunga durata. exec è fire-and-forget con timeout; usa nohup + un file di stato sul target.
    • \n
  • Qualsiasi cosa distruttiva senza istruzione esplicita. Il proxy ti dà il potere — l'umano ti dà il permesso.
    • \n
\n

Recupero errori

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SintomoRimedio
401 al connecttoken scaduto — rileggilo da memory/settings, mai da una trascrizione
sessione 404sessione scaduta (limite 24h) — riconnetti
timeout dell'execalza timeout o spezza il comando; verifica il carico del target
contenuto file corrottohai usato exec invece di SFTP — passa agli endpoint SFTP
\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}