Proxy de assinatura

O proxy de assinatura é um servidor HTTP local que deixa aplicativos externos — OpenViking, Karakeep, Open WebUI, qualquer coisa que fale o formato de conversa compatível com a OpenAI — usarem a sua assinatura de provedor gerenciada pelo Hermes como endpoint de LLM. O proxy anexa as credenciais certas (renovando sozinho), então o aplicativo nunca precisa de uma chave de API fixa.

Isso é diferente do servidor de API:

	Servidor de API	Proxy de assinatura
O que serve	O seu agente (ferramentas, memória, skills)	Inferência crua do modelo
Para que serve	"Usar o Hermes como backend de conversa"	"Usar minha assinatura do Portal em outro aplicativo"
Autenticação	A sua API_SERVER_KEY	Qualquer token (o proxy anexa o de verdade)
Chamadas de ferramenta	Sim — o agente roda as ferramentas	Não — só repasse

Use o servidor de API quando quiser o agente como backend. Use o proxy quando quiser só o modelo, pela sua assinatura.

Começando

1. Entre no provedor (uma vez)

hermes portal

Isso abre o navegador para o fluxo OAuth do Nous Portal. O Hermes guarda o token de renovação em ~/.hermes/auth.json — o mesmo lugar de todos os logins de provedor.

2. Suba o proxy

hermes proxy start

Starting Hermes proxy for Nous Portal
  Listening on:  http://127.0.0.1:8645/v1
  Forwarding to: (resolved per-request from your subscription)
  Use any bearer token in the client — the proxy attaches your real credential.

Deixe rodando em primeiro plano. Use tmux, nohup ou uma unidade do systemd se quiser que sobreviva ao logout.

3. Aponte seu aplicativo para ele

Qualquer configuração compatível com a OpenAI pede o mesmo trio:

URL base:  http://127.0.0.1:8645/v1
Chave:     qualquer coisa (por exemplo, "sk-unused")
Modelo:    Hermes-4-70B    # ou Hermes-4.3-36B, Hermes-4-405B

O proxy ignora o cabeçalho Authorization do seu aplicativo e anexa a credencial real do Portal na requisição de saída. A renovação acontece sozinha quando o token está perto de expirar.

Provedores disponíveis

hermes proxy providers

Hoje: nous (Nous Portal) e xai (xAI / Grok). Mais provedores OAuth podem entrar implementando a interface UpstreamAdapter, em hermes_cli/proxy/adapters/.

Conferir a situação

hermes proxy status

Hermes proxy upstream adapters

  [nous    ] Nous Portal — ready (bearer expires 2026-05-15T06:43:21Z)

Se aparecer not logged in, rode hermes portal. Se aparecer credentials need attention, seu token de renovação foi revogado (raro — acontece se você saiu pela interface web do Portal) — é só rodar hermes portal de novo.

Caminhos permitidos

O proxy só repassa os caminhos que o serviço de destino atende de fato. No Nous Portal:

Caminho	Para que serve
/v1/chat/completions	Conversa (com e sem transmissão contínua)
/v1/completions	Completação de texto no formato antigo
/v1/embeddings	Embeddings
/v1/models	Lista de modelos

Outros caminhos (/v1/images/generations, /v1/audio/speech etc.) devolvem 404, com um erro claro apontando os permitidos. Isso evita que clientes perdidos mandem requisições estranhas adiante.

Configurar o OpenViking para usar o Portal

O OpenViking é um banco de contexto que precisa de um provedor de LLM para o modelo de visão e linguagem (usado para extrair memórias) e para o modelo de embedding. Com o proxy, dá para apontar o vlm.api_base dele para o seu proxy local.

Edite o ~/.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 suba o proxy num terminal, ao lado do openviking-server:

# Terminal 1
hermes proxy start

# Terminal 2
openviking-server

As chamadas de visão e linguagem do OpenViking agora passam pela sua assinatura do Portal. O lado do embedding ainda precisa do provedor dele — o Portal serve /v1/embeddings, mas a escolha do modelo depende do que o seu plano cobre; confira em portal.nousresearch.com/models.

Configurar o Karakeep (ou qualquer aplicativo de resumo)

O Karakeep aceita uma API compatível com a da OpenAI para resumir favoritos. Na configuração dele:

# .env do Karakeep
OPENAI_API_BASE_URL=http://127.0.0.1:8645/v1
OPENAI_API_KEY=qualquer-coisa-nao-vazia
INFERENCE_TEXT_MODEL=Hermes-4-70B

O mesmo padrão funciona no Open WebUI, no LobeChat, no NextChat, ou em qualquer outro cliente compatível.

Expor na rede local

Por padrão o proxy escuta em 127.0.0.1 (só a própria máquina). Para liberar outras máquinas da sua rede:

hermes proxy start --host 0.0.0.0 --port 8645

⚠ Atenção: qualquer pessoa na sua rede passa a usar a sua assinatura do Portal. O proxy não tem autenticação própria — ele aceita qualquer token. Use firewall, VPN ou um proxy reverso com autenticação de verdade se você for expor além da rede de confiança.

Limites de requisição

Os limites de requisições e tokens por minuto do seu plano valem para o proxy inteiro. Ele não distribui nem agrupa — é um token só, com a sua cota completa. Acompanhe o uso em portal.nousresearch.com.

Arquitetura

O proxy é propositalmente mínimo. Por requisição:

1. Recebe o POST /v1/chat/completions do seu aplicativo
2. Consulta a credencial atual do adaptador (renovando, se estiver perto de expirar)
3. Repassa o corpo da requisição literal, com Authorization: Bearer <chave-gerada>
4. Devolve a resposta sem alteração (preservando o SSE)

Sem transformação. Sem registro do corpo das requisições. Sem laço de agente. O proxy é um repasse que anexa credencial.

No futuro: mais provedores OAuth

O sistema de adaptadores é extensível. Acrescentar um provedor (HuggingFace, o endpoint de conversa do GitHub Copilot, a Anthropic por OAuth) exige implementar o UpstreamAdapter em hermes_cli/proxy/adapters/<provedor>.py e registrá-lo em adapters/__init__.py. Provedores que não são compatíveis com a OpenAI no nível do protocolo (a API de mensagens da Anthropic, por exemplo) precisariam de uma camada de transformação, o que está fora do escopo do formato atual.