Design Secret-Source Precedence Across Hermes Profiles

Hermes can combine local environment values, 1Password references, Bitwarden project dumps, command helpers, and plugin sources. A secure design decides ownership before two sources claim the same variable. Hermes enforces deterministic rules, but the operator must still choose a policy that matches the organization.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/secrets/

Understand the ladder

Existing shell or dotenv values win unless the claiming source explicitly allows replacement. Explicitly mapped sources outrank bulk project sources because a variable-to-reference mapping expresses stronger intent. Within the same shape, the first configured source wins; later duplicate claims produce warnings rather than silent replacement. A source cannot overwrite another source’s protected bootstrap token.

Named profiles add another concern. Shared vaults can provide profile-suffixed credential names that hydrate a canonical variable for the matching profile, while a direct canonical value still wins over an alias. Use the preserve list for variables that must always remain local and profile-specific.

Precedence-design checklist

• Inventory every source that can claim each credential variable.
• Classify each source as mapped or bulk.
• Write an explicit source order.
• Decide whether local environment values or central rotation authority should win.
• Protect bootstrap-token variable names.
• Mark profile-specific platform credentials for preservation.
• Use aliases only for credential-shaped variables with clear ownership.
• Review conflict warnings during every new source rollout.

Common pitfalls

• Assuming list order can make a bulk source outrank an explicit mapping.
• Enabling replacement globally without reviewing local emergency credentials.
• Storing one canonical chat-platform token in a shared vault for several profiles.
• Creating both a direct canonical value and an alias without knowing which wins.
• Ignoring startup conflict warnings because the agent still launches.
• Treating provenance labels as cosmetic rather than operational evidence.

Verification steps

1. Build a table of variable, owner, source shape, profile, and replacement policy.
2. Test a local-versus-central conflict and record the winner.
3. Test mapped-versus-bulk conflict regardless of source order.
4. Test two sources of the same shape and confirm the first claim wins.
5. Start two named profiles and confirm each resolves its intended platform credential.
6. Verify protected bootstrap tokens cannot be replaced by fetched values.
7. Save a redacted startup report showing variable names and provenance only.