Operate Hermes with 1Password Secret References

Hermes can resolve API keys from 1Password at process startup through the official op CLI. Instead of copying every provider key into a local dotenv file, the Hermes configuration maps each environment-variable name to an op://vault/item/field reference. Rotation then happens in 1Password and takes effect when the relevant Hermes process starts again.

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

Choose the authentication model

Use an interactive desktop session for a personal laptop where a human can unlock 1Password. Use a narrowly scoped service account for a gateway, cron worker, container, or other non-interactive runtime. The service-account token is still a high-value bootstrap credential: store it only in a protected runtime location, grant it access to the smallest useful vault, and ensure every process that must resolve secrets actually receives it.

Pinning the op binary path can remove ambiguity on managed hosts. Hermes validates references, invokes the CLI with a restricted child environment, and does not treat an empty resolved field as a replacement for a working credential.

Setup checklist

Install the official 1Password CLI and verify the intended account with op whoami.
Choose desktop-session or service-account authentication deliberately.
Keep the bootstrap token out of config.yaml and version control.
Grant read access only to the required vault and items.
Map each provider variable to one exact op:// reference.
Run hermes secrets onepassword sync as a dry run.
Review hermes secrets onepassword status without exposing values.
Restart gateways, workers, and cron runtimes after rotation.

Common pitfalls

Assuming an interactive shell session will be inherited by launchd, systemd, cron, or containers.
Giving a service account access to an entire personal vault.
Leaving a stale local key in place without deciding which source should win.
Mapping an empty or renamed field and accepting the fallback silently.
Publishing screenshots that reveal vault, item, account, or reference names.

Verification steps

Resolve one low-risk test reference with the dry-run command.
Start a fresh Hermes process and confirm the credential is attributed to 1Password.
Verify the resolved value is not copied into ordinary configuration or logs.
Rotate the test field in 1Password and confirm an existing process does not pretend to hot-reload it.
Restart the target runtime and verify the new value is used.
Revoke the service account or lock the desktop session in a controlled test and confirm Hermes reports a useful warning while preserving the configured fallback behavior.
Review the local cache mode and file permissions before production use.