# 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:

| Endpoint | Propósito |
|---|---|
| `POST /connect?target=vps1` | abrir uma sessão → `session_id` |
| `POST /<sid>/exec` `{command, timeout}` | executar um comando (async) → `exec_id` |
| `GET /<sid>/exec/<exec_id>` | consultar a saída |
| Endpoints SFTP | upload/download de arquivos, `ls`, `mkdir`, `rm` |

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

## O padrão de execução

```bash
# 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

| 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 `timeout` ou divida o comando; verifique a carga do alvo |
| conteúdo de arquivo corrompido | você usou `exec` em vez de SFTP — mude para os endpoints SFTP |