Como ligar um agente à RN com a rede restrita

Crie uma saída específica para os modelos

Um container na rede bridge normalmente consegue sair para outros destinos. Expor o serviço apenas em localhost também não restringe as conexões que ele inicia. No Hermes desta série, o agente usou --network none e a interface usou uma rede própria do Bubblewrap.

A única saída externa do agente passou por um socket Unix até um retransmissor confiável no host. O destino desse retransmissor ficou fixo em rota-nacional.ia.br:443. Ele não ofereceu proxy aberto, escolha de host ou resolução de destinos enviada pelo agente.

Monte o canal em três trechos

• Crie no host um diretório privado, com permissão 0700. Nele, abra o socket Unix do transporte. Use systemd-socket-activate para entregar o listener ao systemd-socket-proxyd, com destino rota-nacional.ia.br:443 e --connections-max=64.
• Monte só esse diretório no container. Dentro da rede isolada, abra um listener em 127.0.0.1:443 que retransmita para o socket Unix. Use binários e bibliotecas compatíveis com a imagem.
• Associe rota-nacional.ia.br a 127.0.0.1 apenas dentro do container. O SDK continua usando o hostname original. O TLS atravessa o retransmissor sem terminar nele.
• Confira o certificado para rota-nacional.ia.br. O host resolve o destino pelo resolvedor autorizado. Não use verify=false nem substitua o certificado por um certificado do retransmissor.
• Mantenha outro socket privado para Desktop → agente. Não misture esse canal autenticado com a saída para a RN.

Cadastre uma chave própria no Hermes

No Hermes Desktop v0.22.6, abra Settings → Providers → Custom Endpoints. Na entrada inicial, o caminho equivalente é I have an API key → Local / custom endpoint. Use uma chave RN da organização responsável por esse agente. Não cadastre o segredo do provedor nem uma chave administrativa.

Para conservar o contrato nativo da OpenAI, use a URL base https://rota-nacional.ia.br/v1/providers/openai/v1. Escolha o modo de API exigido pelo fluxo, como Chat Completions ou Responses API, e um modelo disponível no pool autorizado. O gateway preserva corpo, parâmetros e erros do provedor.

A credencial cadastrada fica acessível ao próprio agente. Reduza sua autoridade e confira os limites disponíveis na organização. Antes de repetir um pedido que perdeu a resposta, confira seu estado: uma conexão interrompida não comprova que o provedor deixou de executar.

Escolha quando exigir a barreira de privacidade

O caminho /v1/providers/* é nativo e não anonimiza o conteúdo. A RN ainda controla a autenticação e o pool autorizado, mas preserva o corpo enviado. Se a organização ou o pool exige a barreira, esse caminho retorna 403 organization_privacy_barrier_required.

Para o chat protegido, use a base https://rota-nacional.ia.br/v1, o modo Chat Completions e um modelo rota/* do catálogo. Confira a compatibilidade das ferramentas e do streaming antes da troca. Não suponha que recursos exclusivos de Responses ou de outro provedor sejam convertidos.

A política de conteúdo pode substituir, remover ou bloquear dados identificados. Ela tem limites de cobertura. Não é uma garantia contra todo dado sensível, instrução maliciosa ou ação externa. A escolha de gravar conteúdo e a autorização de envio para fora são controles separados.

Valide a rede e depois o fluxo útil

Tente acessar um serviço do host, a rede local e a internet fora do canal. As tentativas devem falhar. Confira o TLS da RN pelo caminho autorizado. Teste também a recusa de configuração do agente sem token e a leitura com o token correto.

Depois de cadastrar a chave, valide uma conversa com dado sintético, a chamada de ferramenta necessária e os erros esperados. A instalação local desta série provou os canais e a interface, mas não executou inferência por falta de uma chave dedicada. Uma conexão TLS aberta não prova uma conversa concluída.

O destino fixo reduz os lugares que um pacote pode alcançar. Ele não impede abuso de uma operação permitida na RN. O modelo também não deve receber autoridade ampla para enviar mensagens, apagar arquivos ou escrever em sistemas da empresa.

Perguntas frequentes