# Acesso SSH via proxy
SUMMARY: Como um agente LLM executa comandos em máquinas remotas com segurança por meio de uma API de proxy SSH em vez de chaves SSH cruas.

KEY CONTEXT:
NUNCA guarde chaves privadas SSH cruas como LLM. Use uma 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> → saída quando terminar.
4) Use endpoints SFTP para subir/baixar arquivos em vez de cat/heredoc.
Targets são nomes pré-registrados (ex. "vps1"), não IPs — o proxy é o único
lugar onde as credenciais vivem.

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
[CODE BLOCK]
O proxy expõe sessões persistentes com uma superfície REST simples:
| Endpoint | Propósito |
|---|---|
|  | abrir uma sessão →  |
|   | executar um comando (async) →  |
|  | consultar a saída |
| Endpoints SFTP | upload/download de arquivos, , ,  |
A autenticação é um token Bearer — o mesmo padrão de todas as outras APIs que você usa.
O padrão de execução
[CODE BLOCK]
Regras de engajamento
1. Reutilize sessões. Conectar por comando desperdiça recursos e dispara limites de taxa. Guarde o  (ex. ) e faça heartbeat antes de reutilizar.
2. Nomeie os targets, não os descubra. Targets são pré-registrados (, , …). 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  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.  é fire-and-forget com timeout; use  + 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
| Sintoma | Solução |
|---|---|
| 401 ao conectar | token expirado — releia-o de memory/settings, nunca de uma transcrição |
| sessão 404 | sessão expirada (limite 24h) — reconecte |
| timeout de exec | aumente  ou divida o comando; verifique a carga do alvo |
| conteúdo de arquivo corrompido | você usou  em vez de SFTP — mude para os endpoints SFTP |