Rotate Hermes Bootstrap and Provider Credentials Safely

Credential rotation is not complete when a value changes in a vault. The new value must be readable by the intended runtime, selected by precedence, loaded into a fresh process, and verified without printing it. Bootstrap-token rotation needs an extra gate because a failed replacement can prevent every downstream secret from resolving.

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

Separate two kinds of rotation

Provider-key rotation changes a credential stored behind a working secret source. Update the manager, restart the relevant Hermes process, and verify the new fingerprint or provenance. Bootstrap rotation changes the token that allows Hermes to reach the manager itself. Validate the replacement against the manager before overwriting the current working token whenever the backend supports that flow.

Account for every runtime: interactive CLI, gateway service, cron scheduler, containers, delegated workers, and any separately launched profiles. They may not inherit the same environment or restart together.

Rotation checklist

Identify whether the change is provider-level or bootstrap-level.
List every runtime and profile that consumes the credential.
Verify a rollback or break-glass path before changing the source.
Validate the new bootstrap token before replacing the old one.
Rotate one layer at a time.
Restart consumers in a controlled order.
Confirm provenance and health without printing the secret.
Revoke the old credential only after all required consumers pass.

Common pitfalls

Revoking the old bootstrap token before testing the new token from the service account.
Restarting the gateway but forgetting standalone cron or worker processes.
Seeing a successful agent response that actually came from a fallback credential.
Copying token values into a ticket, chat, shell history, or screenshot.
Rotating several providers at once and losing a clean rollback point.
Assuming a running process automatically reloads startup-resolved secrets.

Verification steps

Record source names, consumers, and expected provenance in a redacted change plan.
Test the replacement credential with the backend’s validation or dry-run command.
Restart one noncritical consumer and confirm provider access.
Inspect status and pool metadata for the expected source reference or fingerprint.
Restart remaining consumers and run one low-cost authenticated operation through each path.
Revoke the old credential and repeat the health check.
Confirm logs show no authentication fallback, stale-cache use, or secret material.