Operate Bitwarden Secrets Manager for Hermes

Bitwarden Secrets Manager can provide a project of environment-shaped credentials to Hermes at startup. One machine-account access token becomes the bootstrap credential; the provider keys remain in a centrally managed Bitwarden project where they can be rotated or revoked.

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

Define a narrow project boundary

Create a dedicated Secrets Manager project for the specific Hermes installation or team boundary. Name each secret after the environment variable Hermes expects, such as a provider API-key variable. Grant the machine account read access only to that project. The machine token is autonomous and cannot rely on a human MFA prompt at runtime, so its scope and storage matter more than convenience.

Hermes can install a pinned bws binary and verify its published checksum. Region selection is also part of authentication: a valid EU or self-hosted token sent to the wrong server can look like a bad credential.

Deployment checklist

Create a dedicated Bitwarden Secrets Manager project.
Use environment-variable-shaped secret names.
Grant the machine account read-only project access.
Store BWS_ACCESS_TOKEN only in the protected Hermes runtime environment.
Select the correct US, EU, or self-hosted endpoint.
Run the setup wizard and inspect the variables it can resolve.
Dry-run with hermes secrets bitwarden sync.
Record who owns token rotation and emergency revocation.

Common pitfalls

Confusing the password-manager vault with the Secrets Manager product.
Giving a machine account access to unrelated projects.
Sending an EU token to the default US endpoint.
Assuming the access token is harmless because individual provider keys are external.
Letting a generated project secret overwrite a deliberately profile-specific local value.
Depending on network resolution without defining a safe failure posture.

Verification steps

Run hermes secrets bitwarden status and confirm binary, region, token presence, and project visibility.
Dry-run the project sync and inspect names only.
Start Hermes and confirm the expected provenance label appears.
Rotate one test provider value in Bitwarden, restart Hermes, and verify the new credential is selected.
Revoke a test machine token and confirm the token command validates a replacement before writing it.
Verify checksum failure, timeout, and authentication failure remain visible and do not print secret values.
Review Bitwarden access logs and project membership on a regular schedule.