Acesso SSH via proxy

Agentes precisam executar comandos em máquinas remotas — deployar um contêiner, ler um log, corrigir uma config. Entregar chaves privadas SSH cruas a um LLM é uma má ideia: as chaves acabam em janelas de contexto, logs e transcrições. Um proxy SSH resolve isso: ele detém as credenciais, o agente só fala HTTP.

O modelo

LLM ──HTTPS──► Proxy SSH ──SSH──► máquinas alvo
                (detém as chaves,
                 log de auditoria,
                 limites de taxa)

O proxy expõe sessões persistentes com uma superfície REST simples:

A autenticação é um token Bearer — o mesmo padrão de todas as outras APIs que você usa.

O padrão de execução

# 1. conecte uma vez, reutilize a sessão para toda a task
SID=$(curl -s -H "Authorization: Bearer $KEY" \
  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)

# 2. execute um comando
EID=$(curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -X POST "https://ssh-proxy.example/$SID/exec" \
  -d '{"command": "docker ps --format \"{{.Names}}\"", "timeout": 120}' | jq -r .exec_id)

# 3. consulte o resultado
curl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Regras de engajamento

1. Reutilize sessões. Conectar por comando desperdiça recursos e dispara limites de taxa. Guarde o session_id (ex. /tmp/vps1_sid) e faça heartbeat antes de reutilizar.
2. Nomeie os targets, não os descubra. Targets são pré-registrados (vps1, pi, …). O proxy é a fonte única de verdade — nunca hardcode endereços IP no código do agente.
3. Prefira SFTP a cat/heredoc de shell para arquivos. Escapar dados binários via exec corrompe payloads. Use os endpoints dedicados de upload/download.
4. Quote seus comandos. O corpo JSON é parseado duas vezes (HTTP + shell). Envolva comandos remotos em aspas simples e mantenha-os em uma linha.
5. Assuma a auditoria. Cada exec vai para o log de auditoria do proxy — aja como se o humano lesse tudo (ele pode).

Quando NÃO usar exec

• Ler estado estruturado que tem uma API (Docker, bancos de dados, a Mind API da Synapse) — sempre prefira a API ao parsing de saída de CLI.
• Processos interativos de longa duração. exec é fire-and-forget com timeout; use nohup + um arquivo de status no alvo.
• Qualquer coisa destrutiva sem instrução explícita. O proxy lhe dá o poder — o humano lhe dá a permissão.

Recuperação de erros