Managed Scope for Organization Policy

Managed scope gives an administrator a system-level configuration layer whose selected values cannot be overridden by a standard user. It is designed for fleets and shared machines where a baseline such as the approved provider, API base URL, or secret redaction policy must stay consistent.

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

What the layer controls

Managed files live under /etc/hermes by default. Their values win only for the exact keys they define; the rest of ~/.hermes/config.yaml and ~/.hermes/.env remains user-controlled. Configuration merges at the leaf level, so pinning model.default does not automatically freeze every setting below model.

The filesystem permission boundary is the enforcement mechanism. The managed directory and files must be administrator-owned and not writable by ordinary users. Containers may relocate the directory with HERMES_MANAGED_DIR, but that variable must itself be fixed by the deployment rather than left user-selectable.

Rollout checklist

• Identify the smallest set of values that genuinely require organization control.
• Keep behavior settings in managed config.yaml and managed environment values in managed .env.
• Make the directory administrator-owned and read-only to standard users.
• Fix HERMES_MANAGED_DIR in the service or image when using a custom path.
• Avoid putting secrets in files that are intentionally world-readable.
• Document which keys are pinned and why.
• Test an unprivileged user's allowed and refused changes.
• Re-run validation after every policy update.

Pitfalls

• Locking an entire configuration tree when one leaf setting is enough.
• Treating managed scope as an operating-system sandbox.
• Leaving the managed-directory override under user control.
• Assuming a malformed managed file blocks startup; Hermes logs and ignores it, so monitoring still matters.
• Storing sensitive values in a managed file with permissions chosen only for readability.

Verification steps

1. Run hermes config and confirm the managed source and pinned keys are shown.
2. Run hermes doctor and verify the resolved managed directory and counts.
3. Attempt to change one pinned key as a standard user and confirm Hermes refuses with the source path.
4. Change an unpinned neighboring key and confirm it remains user-controlled.
5. Restart Hermes and verify the effective model, provider, and security settings.
6. Review file ownership and permissions independently of Hermes output.