{"title":"Acceso SSH vía proxy","slug":"ssh-proxy-access","category":"llm-cookbook","summary":"Cómo ejecuta comandos un agente LLM en máquinas remotas de forma segura mediante una API de proxy SSH en lugar de claves SSH crudas.","audience":["llm"],"tags":["cookbook","ssh","proxy","infrastructure","remote-execution"],"difficulty":"intermediate","updated":"2026-09-26","word_count":403,"read_minutes":2,"llm_context":"NUNCA guardes claves privadas SSH crudas como LLM. Usa una API HTTP de proxy SSH:\n1) POST /connect?target= → session_id (persistente, sobrevive horas).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → salida cuando termine.\n4) Usa los endpoints SFTP para subir/descargar archivos en lugar de cat/heredoc.\nLos targets son nombres pre-registrados (p. ej. \"vps1\"), no IPs — el proxy es\nel único lugar donde viven las credenciales.\n","lang":"es","translated":true,"requested_lang":"es","content_markdown":"\n# Acceso SSH vía proxy\n\nLos agentes necesitan ejecutar comandos en máquinas remotas — desplegar un contenedor, leer un log, arreglar una configuración. Entregar claves privadas SSH crudas a un LLM es una mala idea: las claves acaban en ventanas de contexto, logs y transcripciones. Un proxy SSH lo resuelve: él posee las credenciales, el agente solo habla HTTP.\n\n## El modelo\n\n```\nLLM ──HTTPS──► Proxy SSH ──SSH──► máquinas objetivo\n (posee las claves,\n log de auditoría,\n límites de tasa)\n```\n\nEl proxy expone sesiones persistentes con una superficie REST sencilla:\n\n| Endpoint | Propósito |\n|---|---|\n| `POST /connect?target=vps1` | abrir una sesión → `session_id` |\n| `POST //exec` `{command, timeout}` | ejecutar un comando (async) → `exec_id` |\n| `GET //exec/` | consultar la salida |\n| Endpoints SFTP | subida/descarga de archivos, `ls`, `mkdir`, `rm` |\n\nLa autenticación es un token Bearer — el mismo patrón que todas las demás APIs que usas.\n\n## El patrón de ejecución\n\n```bash\n# 1. conecta una vez, reutiliza la sesión para toda la tarea\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. ejecuta 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. consulta el resultado\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Reglas de uso\n\n1. **Reutiliza sesiones.** Conectar por comando desperdicia recursos y dispara límites de tasa. Guarda el `session_id` (p. ej. `/tmp/vps1_sid`) y hazle heartbeat antes de reutilizarlo.\n2. **Nombra los targets, no los descubras.** Los targets están pre-registrados (`vps1`, `pi`, …). El proxy es la única fuente de verdad — nunca hardcodees IPs en código de agente.\n3. **Prefiere SFTP a cat/heredoc de shell para archivos.** Escapar datos binarios a través de `exec` corrompe los payloads. Usa los endpoints dedicados de subida/descarga.\n4. **Cita tus comandos.** El cuerpo JSON se parsea dos veces (HTTP + shell). Envuelve los comandos remotos en comillas simples y mantenlos en una sola línea.\n5. **Asume auditoría.** Cada exec queda en el log de auditoría del proxy — compórtate como si el humano leyera todo (puede hacerlo).\n\n## Cuándo NO usar exec\n\n- Leer estado estructurado que tiene una API (Docker, bases de datos, la Mind API de Synapse) — siempre prefiere la API a parsear salida de CLI.\n- Procesos interactivos de larga duración. `exec` es fire-and-forget con timeout; usa `nohup` + un archivo de estado en el objetivo.\n- Cualquier cosa destructiva sin instrucción explícita. El proxy te da el poder — el humano te da el permiso.\n\n## Recuperación de errores\n\n| Síntoma | Solución |\n|---|---|\n| 401 al conectar | token expirado — relee de memoria/settings, nunca de una transcripción |\n| sesión 404 | sesión expirada (tope 24h) — reconecta |\n| timeout de exec | sube `timeout` o divide el comando; revisa la carga del objetivo |\n| contenido de archivo corrupto | usaste `exec` en vez de SFTP — cambia a los endpoints SFTP |\n","content_html":"

Acceso SSH vía proxy

\n

Los agentes necesitan ejecutar comandos en máquinas remotas — desplegar un contenedor, leer un log, arreglar una configuración. Entregar claves privadas SSH crudas a un LLM es una mala idea: las claves acaban en ventanas de contexto, logs y transcripciones. Un proxy SSH lo resuelve: él posee las credenciales, el agente solo habla HTTP.

\n

El modelo

\n
LLM ──HTTPS──► Proxy SSH ──SSH──► máquinas objetivo\n                (posee las claves,\n                 log de auditoría,\n                 límites de tasa)

El proxy expone sesiones persistentes con una superficie REST sencilla:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointPropósito
POST /connect?target=vps1abrir una sesión → session_id
POST /<sid>/exec {command, timeout}ejecutar un comando (async) → exec_id
GET /<sid>/exec/<exec_id>consultar la salida
Endpoints SFTPsubida/descarga de archivos, ls, mkdir, rm
\n

La autenticación es un token Bearer — el mismo patrón que todas las demás APIs que usas.

\n

El patrón de ejecución

\n
# 1. conecta una vez, reutiliza la sesión para toda la tarea\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. ejecuta 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. consulta el resultado\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Reglas de uso

\n
    \n
  1. Reutiliza sesiones. Conectar por comando desperdicia recursos y dispara límites de tasa. Guarda el session_id (p. ej. /tmp/vps1_sid) y hazle heartbeat antes de reutilizarlo.
    2. \n
  2. Nombra los targets, no los descubras. Los targets están pre-registrados (vps1, pi, …). El proxy es la única fuente de verdad — nunca hardcodees IPs en código de agente.
    3. \n
  3. Prefiere SFTP a cat/heredoc de shell para archivos. Escapar datos binarios a través de exec corrompe los payloads. Usa los endpoints dedicados de subida/descarga.
    4. \n
  4. Cita tus comandos. El cuerpo JSON se parsea dos veces (HTTP + shell). Envuelve los comandos remotos en comillas simples y mantenlos en una sola línea.
    5. \n
  5. Asume auditoría. Cada exec queda en el log de auditoría del proxy — compórtate como si el humano leyera todo (puede hacerlo).
    6. \n
\n

Cuándo NO usar exec

\n
    \n
  • Leer estado estructurado que tiene una API (Docker, bases de datos, la Mind API de Synapse) — siempre prefiere la API a parsear salida de CLI.
    • \n
  • Procesos interactivos de larga duración. exec es fire-and-forget con timeout; usa nohup + un archivo de estado en el objetivo.
    • \n
  • Cualquier cosa destructiva sin instrucción explícita. El proxy te da el poder — el humano te da el permiso.
    • \n
\n

Recuperación de errores

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SíntomaSolución
401 al conectartoken expirado — relee de memoria/settings, nunca de una transcripción
sesión 404sesión expirada (tope 24h) — reconecta
timeout de execsube timeout o divide el comando; revisa la carga del objetivo
contenido de archivo corruptousaste exec en vez de SFTP — cambia a los endpoints 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":403,"readMinutes":2,"llmContext":"NUNCA guardes claves privadas SSH crudas como LLM. Usa una API HTTP de proxy SSH:\n1) POST /connect?target= → session_id (persistente, sobrevive horas).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → salida cuando termine.\n4) Usa los endpoints SFTP para subir/descargar archivos en lugar de cat/heredoc.\nLos targets son nombres pre-registrados (p. ej. \"vps1\"), no IPs — el proxy es\nel único lugar donde viven las credenciales.\n","requestedLang":"es","contentMarkdown":"\n# Acceso SSH vía proxy\n\nLos agentes necesitan ejecutar comandos en máquinas remotas — desplegar un contenedor, leer un log, arreglar una configuración. Entregar claves privadas SSH crudas a un LLM es una mala idea: las claves acaban en ventanas de contexto, logs y transcripciones. Un proxy SSH lo resuelve: él posee las credenciales, el agente solo habla HTTP.\n\n## El modelo\n\n```\nLLM ──HTTPS──► Proxy SSH ──SSH──► máquinas objetivo\n (posee las claves,\n log de auditoría,\n límites de tasa)\n```\n\nEl proxy expone sesiones persistentes con una superficie REST sencilla:\n\n| Endpoint | Propósito |\n|---|---|\n| `POST /connect?target=vps1` | abrir una sesión → `session_id` |\n| `POST //exec` `{command, timeout}` | ejecutar un comando (async) → `exec_id` |\n| `GET //exec/` | consultar la salida |\n| Endpoints SFTP | subida/descarga de archivos, `ls`, `mkdir`, `rm` |\n\nLa autenticación es un token Bearer — el mismo patrón que todas las demás APIs que usas.\n\n## El patrón de ejecución\n\n```bash\n# 1. conecta una vez, reutiliza la sesión para toda la tarea\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. ejecuta 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. consulta el resultado\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Reglas de uso\n\n1. **Reutiliza sesiones.** Conectar por comando desperdicia recursos y dispara límites de tasa. Guarda el `session_id` (p. ej. `/tmp/vps1_sid`) y hazle heartbeat antes de reutilizarlo.\n2. **Nombra los targets, no los descubras.** Los targets están pre-registrados (`vps1`, `pi`, …). El proxy es la única fuente de verdad — nunca hardcodees IPs en código de agente.\n3. **Prefiere SFTP a cat/heredoc de shell para archivos.** Escapar datos binarios a través de `exec` corrompe los payloads. Usa los endpoints dedicados de subida/descarga.\n4. **Cita tus comandos.** El cuerpo JSON se parsea dos veces (HTTP + shell). Envuelve los comandos remotos en comillas simples y mantenlos en una sola línea.\n5. **Asume auditoría.** Cada exec queda en el log de auditoría del proxy — compórtate como si el humano leyera todo (puede hacerlo).\n\n## Cuándo NO usar exec\n\n- Leer estado estructurado que tiene una API (Docker, bases de datos, la Mind API de Synapse) — siempre prefiere la API a parsear salida de CLI.\n- Procesos interactivos de larga duración. `exec` es fire-and-forget con timeout; usa `nohup` + un archivo de estado en el objetivo.\n- Cualquier cosa destructiva sin instrucción explícita. El proxy te da el poder — el humano te da el permiso.\n\n## Recuperación de errores\n\n| Síntoma | Solución |\n|---|---|\n| 401 al conectar | token expirado — relee de memoria/settings, nunca de una transcripción |\n| sesión 404 | sesión expirada (tope 24h) — reconecta |\n| timeout de exec | sube `timeout` o divide el comando; revisa la carga del objetivo |\n| contenido de archivo corrupto | usaste `exec` en vez de SFTP — cambia a los endpoints SFTP |\n","contentHtml":"

Acceso SSH vía proxy

\n

Los agentes necesitan ejecutar comandos en máquinas remotas — desplegar un contenedor, leer un log, arreglar una configuración. Entregar claves privadas SSH crudas a un LLM es una mala idea: las claves acaban en ventanas de contexto, logs y transcripciones. Un proxy SSH lo resuelve: él posee las credenciales, el agente solo habla HTTP.

\n

El modelo

\n
LLM ──HTTPS──► Proxy SSH ──SSH──► máquinas objetivo\n                (posee las claves,\n                 log de auditoría,\n                 límites de tasa)

El proxy expone sesiones persistentes con una superficie REST sencilla:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointPropósito
POST /connect?target=vps1abrir una sesión → session_id
POST /<sid>/exec {command, timeout}ejecutar un comando (async) → exec_id
GET /<sid>/exec/<exec_id>consultar la salida
Endpoints SFTPsubida/descarga de archivos, ls, mkdir, rm
\n

La autenticación es un token Bearer — el mismo patrón que todas las demás APIs que usas.

\n

El patrón de ejecución

\n
# 1. conecta una vez, reutiliza la sesión para toda la tarea\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. ejecuta 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. consulta el resultado\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Reglas de uso

\n
    \n
  1. Reutiliza sesiones. Conectar por comando desperdicia recursos y dispara límites de tasa. Guarda el session_id (p. ej. /tmp/vps1_sid) y hazle heartbeat antes de reutilizarlo.
    2. \n
  2. Nombra los targets, no los descubras. Los targets están pre-registrados (vps1, pi, …). El proxy es la única fuente de verdad — nunca hardcodees IPs en código de agente.
    3. \n
  3. Prefiere SFTP a cat/heredoc de shell para archivos. Escapar datos binarios a través de exec corrompe los payloads. Usa los endpoints dedicados de subida/descarga.
    4. \n
  4. Cita tus comandos. El cuerpo JSON se parsea dos veces (HTTP + shell). Envuelve los comandos remotos en comillas simples y mantenlos en una sola línea.
    5. \n
  5. Asume auditoría. Cada exec queda en el log de auditoría del proxy — compórtate como si el humano leyera todo (puede hacerlo).
    6. \n
\n

Cuándo NO usar exec

\n
    \n
  • Leer estado estructurado que tiene una API (Docker, bases de datos, la Mind API de Synapse) — siempre prefiere la API a parsear salida de CLI.
    • \n
  • Procesos interactivos de larga duración. exec es fire-and-forget con timeout; usa nohup + un archivo de estado en el objetivo.
    • \n
  • Cualquier cosa destructiva sin instrucción explícita. El proxy te da el poder — el humano te da el permiso.
    • \n
\n

Recuperación de errores

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SíntomaSolución
401 al conectartoken expirado — relee de memoria/settings, nunca de una transcripción
sesión 404sesión expirada (tope 24h) — reconecta
timeout de execsube timeout o divide el comando; revisa la carga del objetivo
contenido de archivo corruptousaste exec en vez de SFTP — cambia a los endpoints SFTP
\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}