Dê ao Hermes Agent acesso SSH aos seus servidores sem entregar uma chave

15 de out. de 2026 · Termalin Team ai-agentsmcpsshsecuritytutorial

O Hermes Agent já roda comandos de shell em uma máquina remota. O backend de terminal SSH dele aponta para um host e roda cada comando por ssh. Isso é ótimo para um único servidor. No momento em que você tem mais de um, ou não quer uma chave privada parada na máquina que roda o agente, o backend é a ferramenta errada. A configuração mais limpa é conectar o Hermes a um servidor MCP remoto que alcança os seus servidores por ele — sem chave na máquina do agente, vários hosts, regras por conexão e um registro de auditoria. Este post cobre as duas coisas: como o backend SSH funciona hoje e como, em vez disso, encaixar o Termalin como servidor MCP.

Transparência: nós desenvolvemos o Termalin. Os detalhes do Hermes Agent abaixo vêm da documentação pública e do rastreador de issues dele, verificados em 15 de outubro de 2026.

Como o Hermes Agent usa SSH hoje

O Hermes Agent roda as ferramentas dele por meio de um terminal backend. Um desses backends é o SSH. Você o define em ~/.hermes/config.yaml:

terminal:
  backend: ssh

As credenciais ficam em ~/.hermes/.env:

TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu

O TERMINAL_SSH_PORT tem 22 como padrão, e o TERMINAL_SSH_KEY é um caminho para uma chave privada (o padrão do sistema é usado quando você o deixa em branco). A documentação descreve o mecanismo sem rodeios: ele “roda comandos em um servidor remoto por SSH”, reutiliza a conexão com o ControlMaster e um keepalive de 5 minutos de ociosidade, e cada comando é um ssh … bash -c novo.

Três fatos decorrem desse design, e são o motivo pelo qual as pessoas vão procurar outra coisa:

Um backend significa um host. TERMINAL_SSH_HOST e TERMINAL_SSH_USER são ambos obrigatórios, e o backend não tem inventário de múltiplos hosts. Para trabalhar em um segundo servidor, você reconfigura.
Uma chave privada mora na máquina do Hermes, seja como arquivo, seja pelo ssh-agent do sistema. Qualquer coisa que consiga ler essa máquina pode usar a chave, e a chave abre cada host que confia nela.
O Hermes copia as próprias credenciais para a máquina remota. A documentação observa que, para os backends SSH, Modal e Daytona, o Hermes empurra o seu estado de ~/.hermes/ — arquivos de credenciais, skills, cache — para dentro do sandbox remoto durante a sessão, e sincroniza de volta os arquivos de estado alterados ao encerrar.

A documentação faz, sim, um argumento justo a favor do backend SSH: como o agente roda em uma máquina diferente, ele “não consegue modificar o próprio código”. Esse isolamento é real, e voltamos a ele mais abaixo.

Os problemas que as pessoas enfrentam

O rastreador do hermes-agent tem um grupo reconhecível de issues abertas em torno desses caminhos de SSH. Citadas por número, sem exagerar o que cada uma significa para você:

O backend SSH falha com “path too long for Unix domain socket” quando você usa perfis nomeados (#133436).
O /reload não limpa os ambientes SSH em cache depois de uma mudança de config (#71085).
O modo SSH do desktop tem o seu próprio conjunto: uma sonda no macOS que falha cerca de um segundo depois de iniciar (#80836), e travamentos e timeouts do OpenSSH no Windows (#118983, #138378, #127320).
Uma tempestade de retentativas na inicialização, de cerca de 25 logins SSH por minuto (#134197).
O hermes update falha em redes que bloqueiam a porta 22 (#133439).

Alguns desses são sobre o app de desktop, não sobre o backend, e alguns podem já estar resolvidos quando você ler isto. O que importa é o padrão: o backend SSH é uma casca fina sobre uma conexão ssh, então ele herda cada aresta dessa conexão — inclusive a necessidade de que a porta 22 esteja acessível.

Uma alternativa sem chave: o Termalin como servidor MCP remoto

O Hermes Agent suporta MCP. Ele consegue falar com servidores stdio e com servidores HTTP remotos, seja com um cabeçalho Bearer, seja com OAuth. Essa é a brecha. Em vez de dar ao agente uma chave e um host, você o aponta para um servidor MCP remoto que já sabe como alcançar a sua frota.

O Termalin é um cliente SSH com um servidor MCP hospedado. Cada servidor que você quer alcançável roda um Connector — uma instalação de uma linha que disca para fora e nunca fica à escuta em uma porta, então funciona atrás de NAT e CGNAT, e a porta 22 não precisa estar aberta. No cadastro, o sshd do servidor passa a confiar na autoridade certificadora SSH do Termalin. Cada login então usa um certificado de curta duração limitado à sua conta. Nenhuma chave de longa duração fica na máquina, e nenhuma é entregue ao agente.

Os servidores MCP ficam sob a chave de nível superior mcp_servers em ~/.hermes/config.yaml. Há duas formas de autenticar. Em um VPS — o lugar de sempre onde o Hermes roda — a chave de API é mais simples, então comece por ela.

Opção A — chave de API (melhor em um VPS)

Crie uma chave de API no painel web do Termalin, limite-a aos servidores que este agente deve tocar, defina-a como somente leitura ou com uma lista de comandos permitidos, e dê a ela uma expiração. Coloque-a em ~/.hermes/.env:

TERMALIN_API_KEY=tk_live_your_key_here

Depois adicione o servidor. O Hermes resolve as referências ${VAR} no momento de conectar ao servidor, inclusive dentro de headers:

# ~/.hermes/config.yaml
mcp_servers:
  termalin:
    url: "https://termal.in/api/v1/mcp"
    headers:
      Authorization: "Bearer ${TERMALIN_API_KEY}"

Verifique a conexão e, depois, recarregue o MCP dentro de uma sessão:

hermes mcp test termalin

/reload-mcp

Streamable HTTP é o transporte padrão para servidores com url, e é o que o termal.in fala, então você não precisa de uma linha transport:.

Se o Hermes roda na sua própria máquina com um navegador, o OAuth evita guardar uma chave:

# ~/.hermes/config.yaml
mcp_servers:
  termalin:
    url: "https://termal.in/mcp"
    auth: oauth

hermes mcp login termalin

Na primeira conexão, o Hermes imprime uma URL de autorização, abre o seu navegador quando consegue e espera pelo callback de OAuth em uma porta loopback local. O login do Termalin aceita esse redirecionamento de loopback (http://127.0.0.1:<port>/callback), então o auth: oauth funciona do nosso lado.

Em um VPS headless, o callback de loopback não consegue alcançar o seu notebook. Dois contornos funcionam com o Termalin: cole a URL de redirecionamento de volta no prompt do Hermes, ou encaminhe a porta com ssh -N -L <port>:127.0.0.1:<port> user@host e termine o login no navegador do seu notebook. O Hermes também tem um fluxo de device-code, mas o login do Termalin não o oferece — em um servidor, a chave de API da Opção A é o caminho mais simples.

O que você ganha quando ele está conectado

Depois de hermes mcp test termalin (ou hermes mcp login termalin) e /reload-mcp, as ferramentas do Termalin aparecem para o agente: hosts_list para ver quais servidores ele pode alcançar, ssh_exec e ssh_exec_many para rodar comandos em um ou em vários, sftp_list / sftp_read / sftp_write para arquivos, server_metrics e alerts_list para a saúde, e job_start / job_status / job_stop / job_list para trabalhos que sobrevivem a uma única chamada.

As diferenças práticas em relação ao backend SSH:

Vários servidores de uma vez. O ssh_exec_many roda o mesmo comando em um conjunto de hosts. Não há limite de um host nem reconfiguração para trocar de máquina.
Regras por conexão. No cartão de apps de IA você define uma política de comandos para esta conexão: acesso total, uma lista de comandos permitidos, ou somente leitura. Comece com somente leitura e amplie mais tarde.
Um registro de auditoria. Cada comando que o agente roda é marcado como do agente, gravado e mostrado na grade de monitoramento ao vivo. “O agente fez isto” é um filtro, não uma reconstrução. Veja a auditoria do que um agente faz (em inglês).
Jobs em segundo plano. Uma migração ou um build longo roda como um job, então uma tarefa lenta não bloqueia a sessão nem esbarra em um timeout fixo.
Sem porta aberta. O Connector disca para fora, o que também contorna a classe de problema do “porta 22 bloqueada”.

Revogar o acesso é uma opção, não uma rotação de chaves por todos os hosts. Para o raciocínio por trás dessa troca, veja por que você não deve entregar a sua chave SSH a um agente e raio de impacto (em inglês).

Quando manter o backend SSH, em vez disso

Este não é um caso em que uma opção vence em todas as categorias.

Se você tem exatamente uma máquina, já mantém uma chave na máquina do Hermes e não quer nada mais no meio do caminho, o backend SSH é o que dá menos trabalho de configurar.
O ponto de isolamento da documentação se sustenta: rodar em um host separado significa que o agente não consegue editar o próprio código. O caminho do MCP também mantém essa propriedade, já que os comandos são executados nos seus servidores, não na máquina do agente — mas se o backend SSH já te dá isso e nada mais é preciso, não há motivo para trocar.
As ferramentas de MCP e de monitoramento do Termalin precisam de um plano Pro (US$ 10/mês, ou US$ 8/mês no plano anual — US$ 96/ano), ou do teste de 14 dias, e de um Connector em cada servidor. Uma chave solitária e o backend SSH não custam nada.

Use o Termalin quando você tem vários servidores, quando não quer uma chave na máquina do agente, quando os servidores estão atrás de NAT, ou quando você precisa de regras por conexão e de uma trilha de auditoria. Fique com o backend SSH quando uma chave em um host é, genuinamente, tudo de que você precisa.

Solução de problemas

As ferramentas não aparecem. Rode hermes mcp test termalin, confirme que a url está certa e que a TERMALIN_API_KEY está definida em ~/.hermes/.env. Depois, /reload-mcp dentro da sessão.
401 do endpoint. A chave de API está faltando, errada ou expirada. Crie uma nova no painel web e atualize o ~/.hermes/.env.
A referência ${TERMALIN_API_KEY} é enviada literalmente. O Hermes expande ${VAR} no momento da conexão; garanta que a variável esteja em ~/.hermes/.env (ou no shell que iniciou o Hermes) e reconecte.
O OAuth em um VPS headless nunca conclui. O callback de loopback não consegue alcançar o seu notebook. Encaminhe a porta com ssh -N -L <port>:127.0.0.1:<port> user@host, ou cole a URL de redirecionamento de volta no prompt. Em um servidor, o caminho da chave de API é mais simples.
Transporte errado. Servidores com url assumem Streamable HTTP por padrão, que é o que o termal.in usa. Só defina transport: sse para servidores que falam apenas SSE — não este.

Perguntas frequentes

O Hermes Agent suporta MCP? Sim. Ele se conecta a servidores stdio e a servidores HTTP remotos, com um cabeçalho Bearer ou OAuth, configurados sob mcp_servers em ~/.hermes/config.yaml.

Posso usar isto com o Hermes Agent em um VPS? Sim, e o caminho da chave de API é o mais fácil ali. O fluxo de OAuth precisa de um navegador ou de um dos contornos para ambiente headless acima.

Preciso abrir uma porta nos meus servidores? Não. O Connector disca para fora, então funciona atrás de NAT e CGNAT sem nenhuma porta de entrada. Veja SSH atrás de NAT (em inglês).

A minha chave SSH é entregue ao agente? Não. Os servidores são alcançados com certificados de curta duração emitidos a cada login. Nenhuma chave de longa duração sai do Termalin, e nenhuma é colocada no ambiente do agente.

O Termalin é um cliente SSH multiplataforma com um servidor MCP hospedado, uma custódia de chaves e política de agente por host. Usa um agente diferente? A mesma configuração sem chave funciona para o OpenClaw, o Codex (em inglês) e outros — ou baixe o app para começar.