Escopo gerenciado

O escopo gerenciado deixa um administrador impor uma base de configuração e segredos que um usuário comum, sem privilégio, não consegue sobrescrever. Serve para instalações de frota ou de organização, em que a área de TI precisa fixar, por exemplo, o provedor de modelo, uma URL base compartilhada, ou security.redact_secrets: true em todos os usuários de uma máquina.

Com um escopo gerenciado presente, os valores que ele define vencem o ~/.hermes/config.yaml, o ~/.hermes/.env e até o ambiente do shell — mas exatamente nas chaves que ele fixa. Todo o resto segue sob controle do usuário.

Diferente de uma instalação travada pelo gerenciador de pacotes

Uma instalação gerenciada por gerenciador de pacotes bloqueia toda mudança de configuração e manda você usar o gerenciador. O escopo gerenciado é outro mecanismo: ele injeta valores imutáveis específicos, chave a chave, em vez de travar a configuração inteira. Os dois são independentes e podem coexistir.

Onde fica

O escopo gerenciado é lido de um diretório de sistema, por padrão /etc/hermes:

/etc/hermes/
├── config.yaml     # camada de configuração gerenciada (vence o ~/.hermes/config.yaml)
└── .env            # camada de ambiente gerenciada (vence o ~/.hermes/.env e o shell)

O diretório e os arquivos pertencem ao root (diretório com modo 0755, arquivos 0644): todo mundo lê, só o administrador escreve. Essa permissão do sistema de arquivos é o mecanismo de imposição — o usuário comum lê os arquivos, mas não consegue editar.

Os dois arquivos são opcionais. Um diretório ou arquivo ausente significa simplesmente "sem escopo gerenciado", e a configuração resolve como resolveria sem o recurso.

Mudar o diretório de lugar

O local pode ser trocado pela variável de ambiente HERMES_MANAGED_DIR (para containers ou instalações fora do /etc). É um botão de instalação, como o HERMES_HOME, definido pelo mesmo administrador que é dono dos arquivos gerenciados. Ele nunca é gravado num .env pelo Hermes.

# Aponta o escopo gerenciado para outro diretório (definido pela TI, não pelo usuário)
export HERMES_MANAGED_DIR=/opt/org/hermes-policy

aviso

Um usuário que consegue definir o HERMES_MANAGED_DIR pode apontar o escopo gerenciado para um diretório dele, e assim contorná-lo. Numa instalação de verdade, essa variável precisa ser fixada pelo administrador (na unidade de serviço ou na imagem do container), não deixada aberta ao usuário. O hermes doctor mostra o diretório gerenciado resolvido, então um desvio fica visível.

Precedência

Para as chaves que a camada gerenciada define, a ordem é (o mais alto vence):

Nível	config.yaml	.env
1	/etc/hermes/config.yaml (gerenciado)	/etc/hermes/.env (gerenciado)
2	~/.hermes/config.yaml (usuário)	~/.hermes/.env (usuário)
3	padrões embutidos	ambiente do shell já existente

A mesclagem é por folha: fixar model.default não congela o resto de model.*. Um config.yaml gerenciado assim:

model:
  default: org/standard-model

força o model.default para todo mundo, deixando o model.fallback (e todas as outras chaves) sob controle do usuário.

Sobre a precedência

Nas chaves que fixa, o escopo gerenciado vence o ambiente do shell de propósito — senão não seria "gerenciado". Este é o único lugar que inverte a regra habitual de "variável de ambiente sobrescreve o config.yaml", e vale só para as chaves que a camada gerenciada define.

Ver o que está gerenciado

hermes config        # mostra um cabeçalho com a origem gerenciada e as chaves fixadas
hermes doctor        # informa o diretório gerenciado resolvido e quantas chaves estão fixadas

Se você tentar mudar um valor gerenciado, o Hermes recusa e diz de onde ele vem:

$ hermes config set model.default my/model
Cannot set 'model.default': it is managed by your administrator
(/etc/hermes/config.yaml) and cannot be changed.

O mesmo vale para os segredos gerenciados — o hermes config set e o assistente de configuração não gravam um valor de usuário para uma chave fixada pelo .env gerenciado.

Montar um escopo gerenciado (para administradores)

sudo mkdir -p /etc/hermes

# Fixa alguns valores para todos os usuários desta máquina
sudo tee /etc/hermes/config.yaml >/dev/null <<'YAML'
model:
  provider: nous
security:
  redact_secrets: true
YAML

# Opcionalmente, fixa um valor compartilhado e não sensível
sudo tee /etc/hermes/.env >/dev/null <<'ENV'
OPENAI_API_BASE=https://inference.exemplo.com/v1
ENV

sudo chmod 0755 /etc/hermes
sudo chmod 0644 /etc/hermes/config.yaml /etc/hermes/.env

As mudanças valem na próxima inicialização do Hermes (um arquivo gerenciado malformado é registrado em destaque e ignorado — ele nunca bloqueia a inicialização, mas o administrador deve conferir o hermes doctor para confirmar que a política está sendo aplicada).

Modelo de segurança e limitações (versão 1)

• A imposição é só por permissão de arquivo. Se um usuário tem escrita no diretório gerenciado (ou roda o Hermes como root), o escopo gerenciado vira apenas uma recomendação.
• O .env gerenciado é legível por todos (0644), então qualquer usuário local lê os segredos colocados ali. Use para valores compartilhados e não sensíveis (uma URL base da organização, padrões de recurso), e não para segredos de alta sensibilidade.
• As ferramentas do próprio agente não são bloqueadas de um valor de ambiente gerenciado. Uma variável gerenciada é aplicada na inicialização, mas nada impede o agente de definir outro valor dentro do shell dele. A versão 1 é uma fronteira de conveniência de gestão contra um usuário comum, não um sandbox do qual não se escapa.

Ficam fora do escopo da versão 1, de propósito, e talvez venham depois:

• Uma fronteira dura, da qual o próprio agente não escape.
• Locais gerenciados nativos no macOS e no Windows (a versão 1 é Linux e POSIX primeiro).
• Diretórios de fragmentos (managed.d/), para política em camadas.
• Arquivos gerenciados assinados, com verificação de integridade.
• Entrega por gerenciamento remoto de dispositivos (MDM).
• Permissões mais restritas, por grupo, para os segredos gerenciados.