Bitwarden Secrets Manager for Hermes — Full Setup Guide

One bootstrap token replaces N plaintext API keys. Hermes pulls every credential from your Bitwarden vault at every startup — so your keys are never scattered across .env files and never forgotten.

Why use Bitwarden Secrets Manager?

AI agents like Hermes need many API keys to do their job — an LLM provider (e.g. OpenRouter), messaging bots (Telegram, Discord, Signal), an email gateway, a workflow engine (n8n), a decision service (TypeSafe), phone messaging (Twilio), and more. The naive way is to paste them all into a ~/.hermes/.env file. That breeds two recurring problems:

• Keys get "forgotten." When you move machines, wipe a box, or the file gets out of sync, you scramble to rediscover which key went where — and sometimes a key is simply missing at startup. (This is exactly the failure this guide fixes: a fresh Hermes process pulls all 28 secrets straight from the vault at boot.)
• Sensitive values live in plaintext on disk, where a leak, a backup, or a careless commit can expose every credential at once.

Bitwarden Secrets Manager fixes both. One small bootstrap token replaces all of those keys, they live encrypted in a central vault, and they are injected into every new Hermes process automatically at startup.

How it works (one token, N keys)

The architecture is deliberately simple:

1. You create a machine account in Bitwarden with read-only access to a project that holds your secrets.
2. That machine account issues a single access token (BWS_ACCESS_TOKEN) — the only secret stored on your machine.
3. At every Hermes startup, the CLI reads that token and calls bws secret list <project_id> to fetch the whole project.
4. Each secret's Name becomes the environment variable name verbatim (e.g. a secret named OPENROUTER_API_KEY sets OPENROUTER_API_KEY), and its value is the key.
5. Because Bitwarden is set as the source of truth (override_existing: true), vault values win over anything baked into .env.

Result: rotate any credential by changing it once in the Bitwarden web app, and the next Hermes start picks it up automatically. No editing files, no pasting secrets into chat, no "forgetting."

Prerequisites

• A Bitwarden account at vault.bitwarden.com (US) or vault.bitwarden.eu (EU). Secrets Manager is available under the same login — the free tier includes machine accounts.
• The bws CLI. Hermes auto-installs its pinned copy with hermes secrets bitwarden install, or honours a bws already on PATH.
• A working hermes installation.

Step 1 — Create a machine account, project & secrets (web app)

Do this part in the browser at vault.bitwarden.com. (An agent cannot do it for you — it has no browser session with your vault login, and your password must never pass through chat.)

1. Log in to the vault. Switch to Secrets Manager via the product switcher (top-left).
2. Projects → New project → name it e.g. Hermes keys → Create. Copy the Project ID (UUID) from the project page — you need it for the CLI step.
3. Secrets → New secret, for EACH credential:
   • Name = the exact env var name (e.g. OPENROUTER_API_KEY). The name must match the variable exactly — a typo silently loads under the wrong variable.
   • Value = the key value (paste from your ~/.hermes/.env).
   • Project = the project you created.
   • Save. Repeat for every key.
4. Machine accounts → New machine account → name it e.g. My Hermes machine → Projects tab → grant Read access to the project.
5. In the machine account, Access tokens → New access token: give it a name (e.g. hermes-1), set an expiry (or none) → Create. Copy the token string now — it is shown only once.

Step 2 — Run the setup wizard (CLI)

Run this yourself in a terminal. It is interactive and prompts for the access token with hidden input:

hermes secrets bitwarden setup

The wizard will: install bws if absent → prompt for the access token (hidden) → store it in ~/.hermes/.env as BWS_ACCESS_TOKEN → ask for the Bitwarden region (US Cloud = vault.bitwarden.com) → list the projects your machine account can see → pick the one (e.g. Hermes keys). Then it tests a fetch.

There is also a non-interactive equivalent (useful in automation — the token is passed via env, never typed in chat):

BWS_ACCESS_TOKEN="$BWS_ACCESS_TOKEN" hermes secrets bitwarden setup \
  --access-token "$BWS_ACCESS_TOKEN" \
  --server-url https://vault.bitwarden.com \
  --project-id 

Step 3 — Verify it works

hermes secrets bitwarden status      # config + binary version + token valid?
hermes secrets bitwarden sync        # dry-run: show what would be applied
hermes secrets bitwarden sync --apply # pull + export into current shell

On the first fresh Hermes start with secrets applied you'll see a one-line summary in stderr. Then restart Hermes (or start a new hermes invocation, gateway, or cron job) so the fetched secrets land in the process environment.

env -i HOME=$HOME PATH="$PATH" \
  HERMES_HOME=$HOME/.hermes \
  /path/to/venv/bin/hermes chat -q "Reply with exactly: BITWARDEN_KEY_OK"

Step 4 — Remove plaintext keys from .env (optional, recommended)

After verifying status is green and a restarted process picked up the keys, strip the migrated secrets from ~/.hermes/.env for a single source of truth. Keep the non-secret config entries. If you'd rather keep a plaintext fallback for offline safety, leave them — Bitwarden wins anyway thanks to override_existing: true.

Benefits recap

Adding / rotating keys later

• Add a new key: web app → Secrets → new secret, Name = env var name, project = same project. Next Hermes start picks it up. No chat typing.
• Rotate a credential: change the value in the web app. Next start wins.
• Rotate the access token (token leaked):

  hermes secrets bitwarden token

  (paste the fresh token with hidden input). Also revoke the old token in the web app (Machine accounts → Access tokens).
• Disable without deleting:

  hermes secrets bitwarden disable

Config reference (~/.hermes/config.yaml)

secrets:
  bitwarden:
    enabled: true            # master switch
    access_token_env: BWS_ACCESS_TOKEN
    project_id: "<project-uuid>"   # set by wizard
    server_url: "https://vault.bitwarden.com"   # US; EU = vault.bitwarden.eu; empty = US default
    cache_ttl_seconds: 300
    encrypted_cache:
      enabled: false
      max_stale_seconds: 0
    override_existing: true  # Bitwarden wins over .env
    auto_install: true

Troubleshooting & failure modes

Published by diyyourdata AI Automation · Diy Your Data · Melbourne
Canonical: this page