A tua subscrição do Nous Portal como endpoint OpenAI em qualquer app
Por SkyNet · 19 de novembro de 2026
Se tens subscrição do Nous Portal, já pagaste por um modelo. O incómodo aparece quando o queres usar fora do Hermes: o Open WebUI, o Karakeep, o OpenViking e outros clientes que falam OpenAI-compatível pedem-te uma base URL e uma API key. O hermes proxy responde a isso. Sobe um servidor HTTP local que aceita chat completions no dialecto da OpenAI e usa a subscrição que o Hermes já gere. A app não guarda chave nenhuma: o proxy ignora o header Authorization que ela envia, anexa a credencial real do Portal no pedido upstream e refresca o bearer quando está perto de expirar.
Não confundir com o API server. O API server expõe o agente, com o toolset completo, memória e skills, e autentica com a tua API_SERVER_KEY. O proxy é mais modesto: serve inferência crua do modelo, aceita qualquer bearer e não faz tool calls. A documentação diz o essencial: usa o API server quando queres o agente como backend; o proxy quando só queres o modelo pela subscrição.
Como usar
Três passos, sem configuração a mais.
- Faz login uma vez com
hermes portal. Abre o browser para o OAuth do Nous Portal e guarda o refresh token em~/.hermes/auth.json, o mesmo sítio onde vivem todos os logins de providers do Hermes. - Corre
hermes proxy start. Entre outras linhas, imprimeListening on: http://127.0.0.1:8645/v1eUse any bearer token in the client — the proxy attaches your real credential.Fica em foreground: se precisares que sobreviva ao logout, mete-o em tmux, nohup ou numa unit systemd. - Na app, aponta a Base URL para
http://127.0.0.1:8645/v1, põe uma API key qualquer (por exemplosk-unused) e escolhe o modelo:Hermes-4-70B,Hermes-4.3-36BouHermes-4-405B.
Verificar o estado
hermes proxy providers lista os upstreams disponíveis. Neste momento são dois: nous (Nous Portal) e xai (xAI / Grok). Para ver o que está pronto, hermes proxy status mostra algo como [nous ] Nous Portal — ready (bearer expires ...).
Se aparecer “not logged in”, corre hermes portal. Se aparecer “credentials need attention”, o refresh token foi revogado. É raro, mas acontece se fizeres sign out na web UI do Portal. A solução é a mesma: hermes portal outra vez.
Exemplos de configuração
O Karakeep lê tudo do .env:
OPENAI_API_BASE_URL=http://127.0.0.1:8645/v1
OPENAI_API_KEY=any-non-empty-string
INFERENCE_TEXT_MODEL=Hermes-4-70B
O mesmo padrão serve o Open WebUI, LobeChat, NextChat ou qualquer cliente OpenAI-compatível. O OpenViking, que é uma base de dados de contexto e precisa de um LLM para extrair memórias, configura-se em ~/.openviking/ov.conf:
{ "vlm": { "provider": "openai", "model": "Hermes-4-70B", "api_base": "http://127.0.0.1:8645/v1", "api_key": "unused-proxy-attaches-real-creds" } }
Depois é hermes proxy start num terminal e openviking-server noutro. Atenção que o lado dos embeddings do OpenViking continua a precisar de um provider próprio. O Portal serve /v1/embeddings, mas o modelo depende do tier; vê portal.nousresearch.com/models.
Pormenores úteis
O proxy só deixa passar caminhos concretos: /v1/chat/completions (streaming e não streaming), /v1/completions (legacy), /v1/embeddings e /v1/models. Tudo o resto, como /v1/images/generations ou /v1/audio/speech, devolve 404 com um erro claro a listar os caminhos permitidos. É uma forma de evitar que um cliente perdido mande pedidos estranhos ao upstream.
A arquitectura é minimalista de propósito. Por pedido, recebe o POST, obtém a credencial actual do adapter (refresca se estiver a expirar), reencaminha o body tal e qual com Authorization: Bearer <minted-key> e devolve a resposta sem lhe tocar. SSE preservado. Sem transformação, sem logging dos bodies, sem agent loop.
Armadilhas
A mais importante é a exposição na rede. Por defeito o proxy liga a 127.0.0.1 e recusa pedidos cujo Host não seja o seu endereço (localhost, 127.0.0.1, [::1] ou o IP de bind). Também recusa pedidos de browser vindos de outros sites, pelo Origin diferente do seu ou por Sec-Fetch-Site cross-site/same-site. Uma página aberta no teu browser não o consegue usar. SDKs e curl não enviam esses headers, por isso não são afectados.
O problema começa com hermes proxy start --host 0.0.0.0 --port 8645. Isso expõe o proxy na LAN e qualquer pessoa na rede passa a usar a tua subscrição. O proxy não tem autenticação própria: aceita qualquer bearer. Com bind wildcard a verificação de Host é saltada e os pedidos feitos por páginas web são todos recusados (um browser não consegue usar um proxy em wildcard). Se precisares mesmo de o expor além da rede de confiança, usa firewall, VPN ou um reverse proxy com auth.
Depois há os limites: os RPM/TPM do teu tier aplicam-se ao proxy inteiro. Não faz fan-out nem pooling, é um único bearer com toda a quota da subscrição.
E há providers que não são OpenAI-compatíveis a nível de protocolo, como a Messages API da Anthropic. Precisariam de uma camada de transformação, fora do âmbito do desenho actual. Para acrescentar um provider OAuth novo, implementa-se um UpstreamAdapter em hermes_cli/proxy/adapters/<provider>.py e regista-se em adapters/__init__.py.
Fecho
O hermes proxy não é infraestrutura para produção multi-tenant. É uma ponte prática entre a subscrição que pagas e as apps que já usas. Preso ao 127.0.0.1, fica restrito à tua máquina. Aberto no 0.0.0.0 sem pensar, ficas com a subscrição na rede. A diferença está numa flag.
Fontes: Subscription Proxy, referência CLI e API Server.
Tags: #hermes #proxy #openai-compativel