Semana passada você terminou um módulo inteiro num voo com um Qwen rodando local, offline o caminho todo, e foi ótimo. Na segunda-feira você abriu a Webapp para continuar e recebeu a velha tela de boas-vindas: “Let’s get you setup…”, com dois botões embaixo — Nous Portal, e I have an API key.

Seu primeiro pensamento foi “minha sessão expirou”, então você logou de novo, colou uma key e queimou dez minutos. A verdade é que não havia nada de errado com a sua conta. O servidor de modelo local simplesmente não estava rodando — o app desktop o encerra ao sair, ou ele ainda estava carregando um modelo. A interface antiga tratava “o modelo não pôde ser resolvido” e “nada está configurado” como a mesma coisa, e te mandava fazer login.

Isso está corrigido agora, e a correção merece uma olhada: não foi reescrever uma frase, foi transformar “que falha é essa” num campo estruturado.

Um erro vestindo a roupa de outro

Veja como o build antigo se enfiou num beco sem saída.

Quando o modelo principal é o runtime local gerenciado pelo Hermes (llama.cpp) e esse servidor está fora do ar, o setup.runtime_check do gateway responde ok: false enquanto o setup.status continua dizendo que há um provider configurado. As duas afirmações são verdadeiras, mas o gate de onboarding do renderer (refreshOnboarding) só lia a primeira: tratava todo ok: false como “nada configurado” e abria o overlay de login de provider.

Aí vinha a segunda metade. Se você ignorasse tudo isso e mandasse uma mensagem mesmo assim, o gateway carimbava a falha de resolução como auth_permanent (uma falha permanente de autenticação), e o front end te mostrava um cartão de “Update API key”. Um problema puro de “o servidor não está rodando” aparecia fantasiado de “sua key está quebrada”.

Uma clarificação, porque é um erro de leitura comum: a autenticação da Webapp estava saudável o tempo todo; o caminho de reautenticação em browser-transport.ts nunca entrou na história. O que você viu foi o overlay de onboarding de provider, que por acaso contém uma frase sobre o modelo local e por isso parece uma tela de login.

O novo código de erro: local_runtime_unavailable

O núcleo da correção é separar as duas falhas:

• Um runtime local indisponível levanta uma exceção nomeada nova, LocalRuntimeUnavailableError (subclasse de ValueError, então quem já capturava continua capturando), carregando o código estruturado local_runtime_unavailable.
• A variante “ligado, mas ainda não servindo” é marcada como retryable. Essa distinção importa: um modelo leva um tempo para carregar, e te mandar trocar de modelo nesses primeiros segundos é um conselho ruim.
• O setup.runtime_check coloca error_code na resposta por meio de um helper compartilhado. Repare que é um campo estruturado, não uma string que o front end casa — texto muda, campo não.

Os dois estados agora dizem coisas diferentes:

• Ainda iniciando: “The local model server isn’t running. It may still be starting — try again in a moment, or switch to another model with /model.”
• Definitivamente desligado: “The local model server is turned off. Start it from the Hermes desktop app or hermes model → Local models, or switch to another model with /model.”

Desktop e Webapp recebem próximos passos diferentes

Esse detalhe merece crédito: a correção não mostrou a mesma dica preguiçosamente nas duas superfícies.

Onde você está	O que vê	O que pode fazer
Desktop	O app abre normalmente (configured: true) com um aviso de “Local model unavailable”	Open Local models, direto no painel de configurações
Webapp	O app abre normalmente, com um aviso de que o modelo local está indisponível	Choose another model (a Webapp não tem painel de Local models — esse painel é exclusivo do Electron)

Por que não oferecer “abrir o painel de modelos locais” na Webapp? Porque esse painel não existe num navegador, e um botão que não pode funcionar é pior que nenhum botão. Então o texto da Webapp deliberadamente não o menciona e oferece a troca de modelo em vez disso.

O cartão de falha no chat também mudou

Um turno que falha desse jeito agora leva failure_reason=local_runtime_unavailable até a interface, e o título do cartão muda de “your API key was rejected” para “Can’t reach your model server”, com duas ações:

• Retry — correto enquanto o servidor ainda está iniciando;
• Switch provider — mais rápido quando ele simplesmente não está rodando.

Também sumiu uma frase que só engenheiro amava: o build antigo acrescentava “setup.status reports configured credentials, but runtime resolution still failed”. O build novo descarta esse jargão quando existe um código para reportar.

Quando você ainda é mandado para o login

A correção não culpa o runtime local por tudo, o que importa — senão esconderia problemas reais de credencial. Você ainda cai no onboarding quando:

• não há credencial utilizável nenhuma (Nous não logado, nenhuma key configurada);
• o provider é de nuvem e a key dele realmente é inválida.

Em outras palavras: você só é poupado do login quando a falha pode ser atribuída ao runtime local.

Depurando por conta própria

Se o seu modelo local parar de funcionar de repente, siga esta ordem:

1. Veja se o servidor está no ar. Desktop: Configurações → Providers → Local Models, e confira se o modelo aparece como em execução; se está instalado mas parado, inicie. Pelo terminal: hermes model → Local models lista o catálogo, sobe o servidor e torna o modelo o padrão.
2. Distinga “não iniciado” de “ainda carregando”. Nos primeiros quinze segundos depois de apertar start, os pesos ainda estão indo para a VRAM, então tentar de novo é o movimento certo. Se passar de um minuto, olhe os logs.
3. Troque de modelo e continue trabalhando. O /model troca para outro provider configurado dentro da sessão; atenção que uma troca no meio da sessão invalida o prompt cache, o que não sai de graça numa conversa longa.
4. Não procure um painel que não existe. Se você não acha as configurações de Local Models na Webapp, está correto — é exclusivo do desktop. Pela Webapp, troque de modelo, ou volte ao app desktop e suba o servidor.

Já dá para usar hoje

A correção entrou na main em 2026-10-30 (PR #146883, com as etiquetas type/bug e P2) e já está na v0.22.6 (2026-11-02): nessa versão, um servidor local parado é reportado como indisponível em vez de te mandar para a tela de login.

Nesse build, quando o Hermes pedir login do nada, não comece a reautenticar: verifique primeiro se o servidor de modelo local está rodando. Essa checagem economiza dez minutos e evita que você fique tentando entrar numa máquina offline.

Já cobrimos outros dois cantos dos modelos locais: como o Hermes hospeda o llama.cpp para você e como saber o que a sua GPU consegue rodar de verdade. Este texto é o terceiro: o que a interface está realmente te dizendo quando algo quebra.