Last updated on

Pare de encher .env com API keys: integre o novo cofre externo de secrets do Hermes v0.19 em 5 passos

Quantas API keys estão atualmente no seu arquivo ~/.hermes/.env? OpenAI, Anthropic, GitHub, Telegram, Discord, Cloudflare, AWS — toda vez que você adiciona uma nova integração, cola outra linha SOME_KEY=sk-.... Depois verifica .gitignore três vezes antes de commitar, se manda o arquivo por Slack quando troca de máquina e cola de novo nos secrets do CI. Pior: cada pessoa do time guarda uma cópia local, então ninguém sabe qual versão é a atual, quem alterou o quê ou se alguma key vazou.

Hermes Agent v0.19.0 transforma essa bagunça em uma abstração limpa: SecretSource. Ele permite que o Hermes leia API keys de um cofre externo na inicialização, com suporte nativo para Bitwarden Secrets Manager e 1Password. Você mantém um único token de bootstrap em .env e deixa o cofre cuidar do resto. As keys não precisam mais viver em arquivos .env em texto plano.

Este post oferece uma migração prática em 5 passos. Você não precisa refatorar tudo de uma vez — pode mover primeiro as keys de maior risco e manter um caminho de rollback aberto.

Para a visão geral completa da v0.19.0, consulte nossas notas de release v0.19.0 e o guia de combos de skills.

Por que .env não é a resposta de longo prazo

.env é ótimo para protótipos, mas desmorona quando o Hermes se conecta a uma dúzia de ferramentas e serviços:

  1. Risco de propagação. Cada vez que você copia .env para outra máquina, container ou ambiente de CI, cria outra superfície de vazamento. O GitHub escaneia milhões de secrets commitados acidentalmente todos os anos.
  2. Sem trilha de auditoria. .env não diz quem alterou qual key ou quando. Uma key pode ser rotacionada e o resto do time só descobre quando algo quebra.
  3. Rotação dolorosa. A rotação trimestral de tokens significa editar N arquivos e N pontos de injeção de variáveis de ambiente, depois torcer para não ter esquecido nada.

Um cofre externo de secrets não apenas “esconde texto plano”: ele transforma secrets em recursos controlados, auditáveis e centralmente gerenciados. O SecretSource do Hermes v0.19.0 conecta essa ideia diretamente ao caminho de inicialização do agente, então o agente lê valores do cofre como se fossem variáveis de ambiente comuns.

O que o SecretSource do Hermes v0.19.0 pode fazer

De acordo com as notas de release v0.19.0 e a documentação oficial de Secrets, a interface SecretSource oferece:

  • Múltiplos cofres ao mesmo tempo. Bitwarden Secrets Manager e 1Password podem ser habilitados simultaneamente. Há também uma fonte genérica command para qualquer cofre que imprima linhas KEY=VALUE.
  • Precedência determinística. O Hermes resolve conflitos com uma hierarquia clara: mapeamentos env: explícitos (1Password, command source) vencem pulls massivos de projeto (Bitwarden); dentro do mesmo tipo, a ordem da lista opcional secrets.sources decide; valores de .env e shell vencem por padrão, a menos que a fonte tenha override_existing: true.
  • Avisos de conflito. Se uma fonte posterior também reivindicar uma variável que uma fonte anterior já forneceu, o Hermes avisa em vez de escolher silenciosamente.
  • Rastreabilidade de variáveis. Cada variável injetada registra qual fonte a forneceu — visível no comando status e nos logs de inicialização.
  • Inicialização não bloqueante. Se o cofre estiver inacessível ou a autenticação falhar, o Hermes imprime um aviso de uma linha com a ação recomendada e continua com as credenciais que .env já tiver.

Isso significa que você pode escrever uma configuração como esta sem colocar OPENAI_API_KEY em .env de forma alguma:

secrets:
  onepassword:
    enabled: true
    env:
      OPENAI_API_KEY: "op://Private/OpenAI/api key"
      ANTHROPIC_API_KEY: "op://Private/Anthropic/credential"
    override_existing: true

As próximas cinco seções mostram como colocar isso em prática.

Passo 1: Atualize para o Hermes v0.19.0 e verifique a CLI

SecretSource é um recurso da v0.19.0, então comece verificando a versão:

hermes --version

Depois confirme que o subcomando secrets existe:

hermes secrets --help

Você deve ver bitwarden, onepassword e outros helpers. Se estiver abaixo da v0.19.0, execute o instalador:

# macOS / Linux / WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Windows (PowerShell)
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Passo 2: Escolha um cofre e autentique-se

O Hermes não gerencia a autenticação para você; ele depende do fluxo oficial de cada cofre. Você precisa configurar isso na máquina onde o Hermes roda.

Opção A: Bitwarden Secrets Manager

Você precisa de uma machine account no Bitwarden Secrets Manager, não no cofre de senhas comum do Bitwarden. A machine account é projetada para cargas de trabalho não interativas.

  1. No web app do Bitwarden, mude para Secrets Manager.
  2. Crie um Project (por exemplo, Hermes keys).
  3. Adicione suas provider keys como secrets. O Nome do secret se torna o nome da variável de ambiente esperada pelo Hermes — OPENAI_API_KEY, ANTHROPIC_API_KEY, TELEGRAM_BOT_TOKEN, etc.
  4. Vá em Machine accounts → New machine account e conceda acesso de leitura ao projeto.
  5. Em Access tokens, crie um token (começa com 0., não pode ser recuperado depois) e copie-o.

Guarde esse token em ~/.hermes/.env como BWS_ACCESS_TOKEN:

BWS_ACCESS_TOKEN=0.xxx...

A binary bws é baixada automaticamente em ~/.hermes/bin/ na primeira necessidade — não precisa de brew, apt ou sudo.

Opção B: 1Password

Instale a CLI oficial do 1Password (op) e verifique se funciona:

op --version
op whoami

Laptop / uso interativo: faça login com op signin ou habilite a integração CLI no app do 1Password. O Hermes passará suas variáveis de sessão para o subprocesso op.

Servidor / CI / cron: crie uma service account, conceda acesso de leitura ao cofre relevante e armazene o token em ~/.hermes/.env:

OP_SERVICE_ACCOUNT_TOKEN=ops_...

Nota de segurança: O token de bootstrap (BWS_ACCESS_TOKEN ou OP_SERVICE_ACCOUNT_TOKEN) é ele mesmo um secret de alto valor. Mantenha .env fora do controle de versão e restrinja as permissões do arquivo.

Passo 3: Execute o assistente de configuração e configure a source

O Hermes fornece uma CLI dedicada para cada source. O assistente grava em ~/.hermes/config.yaml (ou ~/.hermes/profiles/<profile>/config.yaml se você estiver usando um perfil nomeado).

Bitwarden

Execute o assistente interativamente:

hermes secrets bitwarden setup

Ou de forma não interativa:

hermes secrets bitwarden setup \
  --access-token "$BWS_ACCESS_TOKEN" \
  --server-url https://vault.bitwarden.com \
  --project-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

A configuração resultante fica assim:

secrets:
  bitwarden:
    enabled: true
    project_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    server_url: "https://vault.bitwarden.com"
    access_token_env: BWS_ACCESS_TOKEN
    override_existing: true
    cache_ttl_seconds: 300

1Password

Execute o assistente:

hermes secrets onepassword setup

Ou com um service-account token:

hermes secrets onepassword setup \
  --account my.1password.com \
  --token-env OP_SERVICE_ACCOUNT_TOKEN \
  --token "$OP_SERVICE_ACCOUNT_TOKEN"

Depois mapeie cada variável de ambiente para uma referência op://:

hermes secrets onepassword set OPENAI_API_KEY    "op://Private/OpenAI/api key"
hermes secrets onepassword set ANTHROPIC_API_KEY "op://Private/Anthropic/credential"
hermes secrets onepassword set TELEGRAM_BOT_TOKEN "op://Private/Telegram/token"

A configuração resultante:

secrets:
  onepassword:
    enabled: true
    env:
      OPENAI_API_KEY: "op://Private/OpenAI/api key"
      ANTHROPIC_API_KEY: "op://Private/Anthropic/credential"
      TELEGRAM_BOT_TOKEN: "op://Private/Telegram/token"
    service_account_token_env: OP_SERVICE_ACCOUNT_TOKEN
    override_existing: true
    cache_ttl_seconds: 300

Usar ambas as sources juntas

Você pode habilitar ambas ao mesmo tempo. Controle a ordem com a lista sources:

secrets:
  sources: [onepassword, bitwarden]
  onepassword:
    enabled: true
    env:
      OPENAI_API_KEY: "op://Private/OpenAI/api key"
  bitwarden:
    enabled: true
    project_id: "..."

Lembre-se de que sources com mapeamentos explícitos (1Password) têm prioridade automática sobre sources massivas (Bitwarden), independentemente da ordem. Dentro do mesmo tipo, a primeira source vence.

Passo 4: Migre as API keys em texto plano para o cofre

4.1 Inventarie as keys do .env

Liste os secrets que o Hermes usa atualmente, agrupados por impacto:

  • Model API keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.
  • Platform tokens: TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN
  • Cloud credentials: AWS_ACCESS_KEY_ID, CLOUDFLARE_API_TOKEN, GCP_API_KEY
  • Third-party tools: GitHub PATs, Sentry DSNs, Stripe keys, etc.

4.2 Crie os secrets no cofre

Bitwarden: no projeto selecionado, crie um secret para cada variável de ambiente. O nome deve corresponder exatamente ao esperado pelo Hermes, por exemplo OPENAI_API_KEY. Quando você executar hermes secrets bitwarden sync, o Hermes listará as variáveis que consegue resolver.

1Password: crie os items e campos correspondentes às suas referências op://vault/item/field. Por exemplo, se você mapeou OPENAI_API_KEY para op://Private/OpenAI/api key, crie um item chamado OpenAI no cofre Private com um campo api key.

Sugestão de ordem de migração: mova primeiro as keys de maior impacto (Stripe, chaves equivalentes a root da AWS, chaves principais de provedores de modelos) e depois as keys read-only de menor risco.

4.3 Reduza o .env e crie um example.env

Depois que uma key estiver no cofre, delete ou comente a linha correspondente em .env. Mantenha apenas o token de bootstrap que a source precisa:

# ~/.hermes/.env
BWS_ACCESS_TOKEN=0.xxx...
# ou para 1Password:
# OP_SERVICE_ACCOUNT_TOKEN=ops_...

Em seguida, crie um example.env com nomes de variáveis e comentários, mas sem valores reais:

# example.env — os valores reais ficam no cofre externo
OPENAI_API_KEY=see-vault
ANTHROPIC_API_KEY=see-vault
TELEGRAM_BOT_TOKEN=see-vault

Novos membros da equipe saberão quais variáveis são esperadas e qual cofre consultar, sem que ninguém precise enviar um .env real.

Passo 5: Verifique, rotacione e mantenha um caminho de rollback

5.1 Verifique se a integração está ativa

Bitwarden:

hermes secrets bitwarden status
hermes secrets bitwarden sync        # dry-run: visualize o que seria aplicado
hermes secrets bitwarden sync --apply  # exporta para o shell atual

1Password:

hermes secrets onepassword status
hermes secrets onepassword sync        # dry-run
hermes secrets onepassword sync --apply  # exporta para o shell atual

Inicie um novo processo do Hermes (ou um cron job, ou o serviço gateway) para que ele capture os valores resolvidos. Você pode confirmar a proveniência no log de inicialização ou no comando status da source.

5.2 Configure lembretes de rotação

A maioria dos cofres permite adicionar um campo ou nota com a data de rotação. Configure um lembrete de 90 dias no calendário. Quando uma provider key mudar, atualize-a apenas no cofre — nada mais. O próximo start do Hermes usará automaticamente o novo valor.

Se o token de bootstrap vazar ou expirar, rotacione-o sem reexecutar todo o assistente:

hermes secrets bitwarden token
hermes secrets onepassword token

Ambos os comandos verificam o token antes de salvá-lo, então um erro de colagem não quebra a configuração atual.

5.3 Mantenha um caminho de rollback

Não tire todas as keys de uma vez. Uma sequência mais segura:

  1. Migração canário: mova uma key não crítica (por exemplo, uma API de pesquisa read-only) para o cofre e verifique.
  2. Observação com dual-write: mantenha o cofre e .env preenchidos, mas ative override_existing: true na source. Observe por alguns dias.
  3. Limpeza final: quando estiver estável, delete as chaves correspondentes de .env e mantenha apenas o token de bootstrap.

Se algo der errado, o rollback mais rápido é desabilitar a source:

hermes secrets bitwarden disable
hermes secrets onepassword disable

O Hermes volta imediatamente a usar apenas as credenciais de .env.

Armadilhas comuns

  1. Colocar secrets reais em config.yaml. config.yaml deve conter apenas referências (op://...) e IDs de projeto. Os valores reais devem permanecer no cofre.

  2. Armazenar o token de bootstrap do cofre em um .env compartilhado e commitá-lo. BWS_ACCESS_TOKEN e OP_SERVICE_ACCOUNT_TOKEN são tokens de alto valor. Mantenha .env fora do controle de versão e restrinja as permissões do arquivo.

  3. Achar que .env perde prioridade automaticamente. Por padrão, .env e exports de shell vencem. Se uma source tiver override_existing: false e ainda houver keys antigas em .env, o Hermes continuará usando os valores de .env. Defina override_existing: true quando quiser que o cofre seja a fonte da verdade.

  4. Ignorar avisos de conflito. Quando várias sources fornecem a mesma variável, o Hermes avisa. Não silencie o aviso até confirmar qual source deve vencer, ou use secrets.preserve_existing para manter variáveis específicas em .env.

  5. Usar desbloqueio interativo em um servidor. op signin ou sessões BW_SESSION funcionam bem em laptops, mas cron, gateway e CI devem usar service accounts ou machine accounts com tokens não interativos.

  6. Esquecer de atualizar example.env. Depois que os secrets são externalizados, example.env se torna a única documentação das variáveis esperadas. Mantenha-o sincronizado com a estrutura real do cofre.

Combine com aprovações mais inteligentes

Tirar as keys de .env é a metade estática da história de segurança. A v0.19.0 também habilita por padrão as Smart Approvals: quando o Hermes quer executar um comando sinalizado, um reviewer LLM independente o avalia em vez de pedir aprovação para cada um. Combinado com o cofre externo, você tem duas camadas de proteção:

  • Segurança estática: os secrets não chegam em texto plano ao disco, não se propagam entre máquinas e são auditáveis.
  • Segurança dinâmica: operações de risco recebem uma segunda opinião, então uma única chamada de ferramenta excessiva não pode exfiltrar uma key.

Resumo

O SecretSource do Hermes v0.19.0 muda o gerenciamento de API keys de “copiar e colar em .env” para “injetar de um cofre externo na inicialização”. Cinco passos:

  1. Atualize para a v0.19.0 e confirme que hermes secrets existe.
  2. Autentique-se com Bitwarden Secrets Manager ou 1Password e guarde o token de bootstrap em .env.
  3. Execute o assistente e configure a source em config.yaml.
  4. Migre as keys de .env para o cofre, deixando apenas o token de bootstrap.
  5. Verifique com status / sync, rotacione no cofre e mantenha um caminho de rollback.

Seu .env pode passar de dezenas de linhas de secrets para um único token de bootstrap, enquanto o Hermes continua obtendo todos os secrets necessários na inicialização. O onboarding de novos membros não envolve mais trocar arquivos secretos, e a rotação de tokens não significa mais vasculhar dezenas de configurações locais.

Referências: