Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

OAuth por SSH / máquinas remotas

Alguns provedores do Hermes — Spotify e servidores MCP remotos (Linear, Sentry, Atlassian, Asana, Figma, …) — usam um fluxo OAuth de redirecionamento para loopback. O servidor de autorização redireciona seu navegador para http://127.0.0.1:<porta>/callback para que um pequeno ouvinte HTTP iniciado pelo Hermes pegue o código de autorização.

Isso funciona perfeitamente quando o Hermes e o seu navegador estão na mesma máquina. E quebra no instante em que não estão: o navegador do seu notebook tenta alcançar o 127.0.0.1 do seu notebook, mas o ouvinte está preso ao 127.0.0.1 do servidor remoto.

A solução é um encaminhamento local de SSH de uma linha. Para servidores MCP em um terminal interativo, muitas vezes dá para colar a URL de redirecionamento de volta (sem túnel).

O OAuth do xAI Grok (xai-oauth) usa código de dispositivo, não callback em loopback — abra a URL de verificação impressa em qualquer navegador e o Hermes fica consultando até a aprovação. Não precisa de túnel SSH. Veja OAuth do xAI Grok.

Resumo rápido​

# Na sua máquina local (notebook), em um terminal separado:
ssh -N -L 43827:127.0.0.1:43827 usuario@maquina-remota

# Na sessão SSH que você já tem na máquina remota:
hermes auth spotify --no-browser
# → O Hermes imprime uma URL de autorização. Abra-a num navegador do seu notebook.
# → Seu navegador redireciona para 127.0.0.1:43827/callback, o túnel encaminha
#   a requisição ao ouvinte remoto e o login se completa.

O Hermes imprime a porta exata em que se prendeu na linha Waiting for callback on ... — copie de lá. O Spotify usa a porta 43827 por padrão.

Quais provedores precisam disso​

ProvedorPorta de loopbackPrecisa de túnel?
Spotify43827 (padrão)Sim, quando o Hermes está remoto
Servidores MCP (auth: oauth)escolhida automaticamente por servidorSim, quando o Hermes está remoto (ou cole a URL de redirecionamento)
xai-oauth (Grok SuperGrok)não se aplicaNão — fluxo de código de dispositivo
anthropic (Claude Pro/Max)não se aplicaNão — fluxo de colar o código
openai-codex (ChatGPT Plus/Pro)não se aplicaNão — fluxo de código de dispositivo
minimax, nous-portalnão se aplicaNão — fluxo de código de dispositivo

Se o seu provedor não está na tabela, você não precisa de túnel.

Servidores MCP​

Servidores MCP remotos (Linear, Sentry, Atlassian, Asana, Figma etc.) usam o mesmo fluxo de redirecionamento para loopback. O Hermes escolhe automaticamente uma porta livre por servidor e imprime a URL de autorização quando o fluxo OAuth começa — seja na inicialização (quando um servidor novo aparece em mcp_servers:), seja quando você roda hermes mcp login <servidor>.

Você tem dois jeitos de concluir isso de uma máquina remota:

Opção 1 — colar a URL de redirecionamento de volta (sem preparo, funciona em qualquer lugar). Em um terminal interativo, o Hermes pede que você cole a URL de redirecionamento, em paralelo com o ouvinte local. Depois de aprovar no navegador, o redirecionamento para http://127.0.0.1:<porta>/callback vai mostrar um erro de conexão — isso é esperado. Copie a URL inteira da barra de endereços do navegador e cole no prompt do Hermes:

  MCP OAuth: authorization required.
  Open this URL in your browser:

    https://mcp.linear.app/authorize?response_type=code&...

  Or paste the redirect URL here (or the ?code=...&state=... portion) and press Enter:
> https://mcp.linear.app/callback?code=abc123&state=xyz
  Got authorization code from paste — completing flow.

Uma query string solta ?code=...&state=... também é aceita. Isso funciona para qualquer servidor MCP com auth: oauth e não exige mudança nenhuma na configuração de SSH.

Opção 2 — encaminhamento de porta por SSH (igual ao Spotify). O Hermes imprime a porta exata em que se prendeu na dica sobre sessão SSH. Abra um terminal separado no seu notebook:

ssh -N -L <porta>:127.0.0.1:<porta> usuario@maquina-remota

Depois abra a URL de autorização no navegador normalmente; o redirecionamento passa pelo túnel e o ouvinte o recebe. Use isso quando o fluxo precisa se completar sem ninguém acompanhando (por exemplo, uma reautenticação por script em que não dá para colar interativamente).

Pegadinha — a corrida de 30s na recarga de configuração. Se você editar o ~/.hermes/config.yaml para adicionar um servidor MCP com OAuth de dentro de uma sessão do Hermes já rodando, a CLI recarrega as conexões MCP automaticamente com um tempo limite de 30s. Isso não é tempo suficiente para concluir um fluxo OAuth interativo, e a recarga desiste. Use hermes mcp login <servidor> em um terminal novo — ele não tem esse teto e espera os 5 minutos completos até você colar de volta.

Por que o ouvinte não pode simplesmente escutar em 0.0.0.0​

O Spotify e a maioria dos servidores OAuth de MCP validam o parâmetro redirect_uri contra uma lista de permissão. Os dois exigem a forma de loopback (http://127.0.0.1:<porta-exata>/callback). Prender o ouvinte a 0.0.0.0 ou a outra porta faria o servidor de autorização rejeitar a requisição como divergência de redirect_uri. O túnel SSH mantém a URI de loopback intacta de ponta a ponta.

Passo a passo: um salto de SSH​

1. Suba o túnel a partir da sua máquina local​

# Spotify (porta 43827)
ssh -N -L 43827:127.0.0.1:43827 usuario@maquina-remota

O -N quer dizer "não abra um shell remoto, só segure o túnel aberto". Deixe esse terminal rodando enquanto durar o login.

2. Em outra sessão SSH, rode o comando de autenticação​

ssh usuario@maquina-remota
hermes auth spotify --no-browser

O Hermes detecta a sessão SSH, não abre o navegador sozinho e imprime uma URL de autorização mais uma linha Waiting for callback on http://127.0.0.1:<porta>/callback.

3. Abra a URL no navegador local​

Copie a URL de autorização do terminal remoto e cole no navegador do seu notebook. Aprove a tela de consentimento. O servidor de autorização redireciona para http://127.0.0.1:<porta>/callback. Seu navegador bate no túnel, a requisição é encaminhada ao ouvinte remoto e o Hermes imprime Login successful!.

Você pode derrubar o túnel (Ctrl+C no primeiro terminal) assim que ver a linha de sucesso.

Passo a passo: através de um bastião​

Se você chega ao Hermes por um bastião / máquina de salto, use o -J (ProxyJump) embutido do SSH:

ssh -N -L 43827:127.0.0.1:43827 -J usuario-salto@maquina-salto usuario@maquina-final

Isso encadeia uma conexão SSH pela máquina de salto sem colocar a porta de loopback no bastião. O 127.0.0.1:43827 local do seu notebook faz túnel direto até o 127.0.0.1:43827 da máquina remota final.

Em versões antigas do OpenSSH que não suportam -J, a forma longa é:

ssh -N \
    -o "ProxyCommand=ssh -W %h:%p usuario-salto@maquina-salto" \
    -L 43827:127.0.0.1:43827 \
    usuario@maquina-final

Mosh, tmux, ssh ControlMaster​

O túnel é uma propriedade da conexão SSH que está por baixo. Se você roda o Hermes dentro do tmux por cima de uma sessão mosh, a itinerância do mosh não carrega o encaminhamento -L. Abra uma sessão SSH comum separada só para o túnel -L — é essa conexão que precisa continuar viva durante o fluxo de autenticação. Sua sessão interativa mosh/tmux pode seguir rodando o Hermes normalmente.

Se você usa ssh -o ControlMaster=auto, os encaminhamentos de porta em uma conexão multiplexada compartilham o tempo de vida do mestre. Reinicie o mestre se o túnel não subir:

ssh -O exit usuario@maquina-remota
ssh -N -L 43827:127.0.0.1:43827 usuario@maquina-remota

Solução de problemas​

bind [127.0.0.1]:43827: Address already in use​

Alguma coisa no seu notebook já está usando essa porta. Ou o túnel anterior não fechou direito, ou um Hermes local também está escutando nela. Ache e mate o culpado:

# macOS / Linux
lsof -iTCP:43827 -sTCP:LISTEN
kill <PID>

Depois repita o comando ssh -L.

A autorização expirou esperando o callback local​

O redirecionamento nunca chegou de volta ao ouvinte remoto. Confira se o túnel continua vivo (o ssh -N não mostra saída, então olhe o terminal de onde você o iniciou), confirme que você usou a porta da última linha Waiting for callback on ... (o Hermes pode pular para outra porta se a preferida estiver ocupada), reinicie o túnel se precisar e rode o comando de autenticação de novo.

Os tokens vão parar no ~/.hermes errado​

Os tokens são gravados sob o usuário Linux que rodou hermes auth add .... Se o seu gateway / serviço systemd roda com outro usuário (por exemplo, root ou um usuário hermes dedicado), autentique-se como aquele usuário, para os tokens caírem no ~/.hermes/auth.json dele. Use sudo -u hermes -i ou equivalente.

Veja também​