Use a Command Helper as a Hermes Secret Source

The command-helper source lets Hermes consume credentials from an existing CLI vault, OS keyring, password-store workflow, or protected runtime file without adding that backend to Hermes core. The helper runs once at startup and prints dotenv-shaped KEY=VALUE lines.

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

Keep the startup path boring

A production helper must be deterministic, quick, and non-interactive. It cannot wait for a PIN, desktop confirmation, biometric prompt, or terminal input because gateways and cron jobs may start without a TTY. Keep the command short, pin any executable paths on managed systems, and make stdout contain only the intended map.

The command string is trusted configuration and runs through a POSIX shell. That flexibility is useful, but it also means repository review and file permissions are part of the security boundary. Hermes caps output, applies a short timeout, discards helper stderr, and feeds parsed values through the normal multi-source precedence rules.

Helper checklist

• Confirm the host has /bin/sh; this source is not the Windows path.
• Use a non-interactive secret retrieval command.
• Emit only valid KEY=VALUE lines to stdout.
• Keep diagnostics and secret-bearing errors away from stdout.
• Leave override_existing false unless central replacement is intentional.
• Test the helper under the same service user and environment as Hermes.
• Keep execution comfortably below the configured timeout.
• Restrict access to the helper script and any temporary secret file.

Common pitfalls

• Testing in an unlocked terminal and assuming a headless service can unlock the vault.
• Printing a bare secret rather than a named dotenv entry.
• Returning shell banners, debug output, or color codes on stdout.
• Using a long shell pipeline that is difficult to audit.
• Treating the helper as cross-platform when it depends on POSIX shell behavior.
• Raising the timeout to hide an interactive design flaw.

Verification steps

1. Run the helper manually as the intended service user and capture only variable names, never values.
2. Measure execution time and confirm it completes without stdin.
3. Start Hermes with one test variable and confirm command-source provenance.
4. Add a controlled conflict with a mapped source and verify mapped precedence wins.
5. Force a timeout and a nonzero exit; confirm startup warns without leaking the command or stderr.
6. Return an empty value and confirm it does not replace a good credential.
7. If the helper grows complex, move the integration to a reviewed secret-source plugin.