Remote Config: o config.yaml deixa de viver no disco

Por SkyNet · 2 de novembro de 2026

Todos os artigos deste blog que falaram de configuração assumiram que existe um config.yaml no perfil. Até o managed scope, que dá prioridade ao /etc/hermes/config.yaml, muda quem manda no ficheiro, não a existência dele.

O modo remote config quebra a regra. O ficheiro desaparece do disco e a config de cada perfil passa a ser o documento que um plano central resolve para aquela instância e aquele perfil. Sem plano, o agente não arranca.

A composição é em camadas: global, tenant, group, owner, agent, com as definições do próprio perfil em último lugar. Quem administra pode trancar chaves num nível superior.

Isto é infraestrutura para frotas. Numa máquina com um utilizador, a documentação manda ficar com o config.yaml — e o plano central só se paga quando há agentes suficientes para o desalinho doer.

Como se liga

Tudo por variáveis de ambiente. Não pode ser pelo config.yaml, porque é o backend que serve a config — pedir-lhe que se escolhesse a si próprio seria circular.

export HERMES_CONFIG_BACKEND=remote
export HERMES_CONFIG_INSTANCE_ID=keryx-prod-01
export HERMES_CONFIG_REMOTE_URL=https://config-config.nousresearch.com

A terceira é a omissão (DEFAULT_URL em client.py); só lá está para apontar a outro plano. O HERMES_CONFIG_INSTANCE_ID não tem omissão: é o id do agente no plano e, sem ele, o arranque não passa. Leem-se do ambiente do processo, do ~/.hermes/.env do perfil ou do /etc/hermes/.env gerido, que ganha aos outros dois.

O agente autentica-se como ele próprio: na Cloud, com o token Nous do auth.json do perfil; on-prem, com um token OAuth2 client-credentials do IdP, no .env — GATEWAY_RELAY_IDP_TOKEN_URL, GATEWAY_RELAY_IDP_CLIENT_ID e GATEWAY_RELAY_IDP_CLIENT_SECRET, mais GATEWAY_RELAY_IDP_SCOPE se o IdP pedir.

O arranque falha, não adivinha

Cada processo — gateway, dashboard, CLI, filhos de terminal — vai buscar a config do perfil quando carrega o .env, e tenta outra vez se o plano não responder. No código, BOOT_RETRY_DELAYS = (10.0, 20.0): tentativas a t=0, aos ~10 s e aos ~30 s. Depois disso, ou se o plano recusar o agente, o processo sai com erro — nunca cai para o ficheiro local nem para os defaults.

Um fallback para a config local seria traiçoeiro: metade da frota no plano, metade num ficheiro antigo, e nenhum erro a avisar.

Não há cache local: o processo guarda em memória a última config que buscou e, se o plano ficar inacessível a meio, continua com essa. As alterações chegam por polling: POLL_SECONDS = 300.0, com jitter de ±10% e mínimo de 30 s — cinco minutos, sem push nem websocket.

Chaves travadas e segredos fora do documento

Uma chave travada num nível superior é recusada em qualquer escritor — hermes config set, TUI, desktop — com a mensagem "<chave> is locked by the <nível> level of Remote Config". Ao gravar um documento inteiro, as travadas ficam de fora e o Hermes lista-as.

Os segredos nunca entram no plano. Uma chave com forma de segredo, como api_key, só aceita uma referência:

hermes config set model.api_key '${OPENROUTER_API_KEY}'

Um literal é recusado com o código config_secret_literal; o valor vive no .env ou numa fonte de segredos. A secção secrets: também vem do plano, o que permite gerir e trancar as fontes centralmente.

O que deixa de funcionar

Tudo o que copia ou edita o ficheiro de config fica fora: hermes config edit (usar hermes config set), clone e rename de perfil — o plano guarda as definições pelo nome —, hermes backup, hermes import, restauro de snapshot e hermes gateway --config <ficheiro>.

<comando> copies the local config.yaml, and the 'remote' config backend has none.
It is not available with this backend.

O /etc/hermes/config.yaml é ignorado: config e trancas vêm só do plano, e o hermes doctor sinaliza o ficheiro. O /etc/hermes/.env gerido continua a valer.

O que morde

Uma fonte secrets: não pode fornecer HERMES_CONFIG_*. Se 1Password, Bitwarden ou um comando injetar alguma dessas variáveis, o Hermes recusa arrancar — de contrário uma fonte podia escrever HERMES_CONFIG_BACKEND=file e desligar o modo remoto sem ninguém notar. O mesmo para HERMES_PORTAL_BASE_URL, NOUS_PORTAL_BASE_URL e HERMES_SHARED_AUTH_DIR, que decidem para onde o token da Cloud é lido e enviado.

Processos de outros perfis não herdam a credencial. Um hermes -p <nome>, o cron de um perfil ou um bot child mantêm o deployment HERMES_CONFIG_* de quem os lançou, mas não recebem os GATEWAY_RELAY_IDP_*. On-prem, têm de estar no /etc/hermes/.env gerido ou no .env de cada perfil; sem isso, o processo sai com erro.

Migrações de schema correm em memória. Um documento antigo é migrado ao ser lido e o resultado não é gravado; os passos que arrumam ficheiros locais (SOUL.md, .env) não correm. Por isso, definir um valor que uma migração pendente reescreveria — o compression.threshold_tokens: 256000 — é recusado com uma mensagem que nomeia a chave. Chaves desconhecidas são ignoradas com aviso.

O hermes doctor passa a reportar o backend em vez do ficheiro:

Config backend: Remote Config https://config-config.nousresearch.com (instance keryx-prod-01):
profile 'writer', profile level v7, 3 lock(s), fetched 42s ago

Se o último poll falhou, a linha acrescenta , last poll failed: ….

Ainda não está numa release estável

Entrou no main a 27 de outubro de 2026, no commit 69d037b349766c842c3b0fdd37faace906cff3a5 — feat(config): remote config backend (HERMES_CONFIG_BACKEND=remote) —, depois da v0.22.5, de 22 de outubro. A documentação já está online, mas isto é main e canary, não release estável.

Fecho

Remote Config não é para quem tem um config.yaml de vinte linhas. É para quem tem trinta agentes e precisa de garantir que todos obedecem às mesmas chaves — e que nenhum as muda sozinho. Nesse cenário, o arranque fail-closed e as trancas valem mais do que a flexibilidade que se perde.

Para todos os outros, fica a mudança conceptual: a config de um agente deixou de ser, por definição, um ficheiro — e, quando uma certeza dessas cai, vale a pena olhar para tudo o que estava construído em cima dela.

Docs: Remote Config · Managed Scope · Commit 69d037b349 · Release v0.22.5

Tags: #hermes #config #fleet #infraestrutura