# Acceso SSH vía proxy
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.

KEY CONTEXT:
NUNCA guardes claves privadas SSH crudas como LLM. Usa una API HTTP de proxy SSH:
1) POST /connect?target=<name> → session_id (persistente, sobrevive horas).
2) POST /<session_id>/exec {command, timeout} → exec_id.
3) GET /<session_id>/exec/<exec_id> → salida cuando termine.
4) Usa los endpoints SFTP para subir/descargar archivos en lugar de cat/heredoc.
Los targets son nombres pre-registrados (p. ej. "vps1"), no IPs — el proxy es
el único lugar donde viven las credenciales.

Acceso SSH vía proxy
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.
El modelo
[CODE BLOCK]
El proxy expone sesiones persistentes con una superficie REST sencilla:
| Endpoint | Propósito |
|---|---|
|  | abrir una sesión →  |
|   | ejecutar un comando (async) →  |
|  | consultar la salida |
| Endpoints SFTP | subida/descarga de archivos, , ,  |
La autenticación es un token Bearer — el mismo patrón que todas las demás APIs que usas.
El patrón de ejecución
[CODE BLOCK]
Reglas de uso
1. Reutiliza sesiones. Conectar por comando desperdicia recursos y dispara límites de tasa. Guarda el  (p. ej. ) y hazle heartbeat antes de reutilizarlo.
2. Nombra los targets, no los descubras. Los targets están pre-registrados (, , …). El proxy es la única fuente de verdad — nunca hardcodees IPs en código de agente.
3. Prefiere SFTP a cat/heredoc de shell para archivos. Escapar datos binarios a través de  corrompe los payloads. Usa los endpoints dedicados de subida/descarga.
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. Asume auditoría. Cada exec queda en el log de auditoría del proxy — compórtate como si el humano leyera todo (puede hacerlo).
Cuándo NO usar exec
- 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.
- Procesos interactivos de larga duración.  es fire-and-forget con timeout; usa  + un archivo de estado en el objetivo.
- Cualquier cosa destructiva sin instrucción explícita. El proxy te da el poder — el humano te da el permiso.
Recuperación de errores
| Síntoma | Solución |
|---|---|
| 401 al conectar | token expirado — relee de memoria/settings, nunca de una transcripción |
| sesión 404 | sesión expirada (tope 24h) — reconecta |
| timeout de exec | sube  o divide el comando; revisa la carga del objetivo |
| contenido de archivo corrupto | usaste  en vez de SFTP — cambia a los endpoints SFTP |