1Password

Resolve provider API keys from 1Password at process startup instead of storing them in plaintext inside ~/.hermes/.env. You keep your keys as 1Password items and reference them by op://vault/item/field; rotating a credential becomes a single change in 1Password.

How it works

1. You install the official 1Password CLI (op) and authenticate it — either with a service-account token (headless servers) or an interactive/desktop session (your laptop).
2. You map environment-variable names to op:// references in ~/.hermes/config.yaml.
3. Every time hermes (or the gateway, or a cron job) starts, after ~/.hermes/.env has loaded, Hermes runs op read for each reference and sets the resolved values into os.environ.
4. By default Hermes overrides values already in your environment, so 1Password is the source of truth — rotate a credential once and every Hermes process picks it up on next start. Flip override_existing: false if you want .env to win instead.

Hermes never authenticates on your behalf and never downloads op: it shells out to your already-installed, already-trusted CLI. If op is missing, your session is locked, or a reference is wrong, Hermes prints a one-line warning and continues with whatever credentials .env already had — it never blocks startup.

Authentication

op supports two non-interactive-friendly modes; Hermes works with either:

• Service accounts (recommended for servers/CI): create a service account in 1Password, grant it read access to the relevant vault, and export its token as OP_SERVICE_ACCOUNT_TOKEN in ~/.hermes/.env. The token is the credential — treat it like any other bearer token.
• Desktop / interactive sessions (laptops): run op signin (or enable CLI integration in the 1Password app). Hermes passes your OP_SESSION_* variables through to the op child process. The 1Password cache key includes those session variables, so signing into a different account never serves a value cached under the previous identity.

Bootstrap token

When you authenticate with a service-account token, that token is itself the bootstrap credential Hermes needs before it can resolve any op:// reference. It must be present in os.environ of every process that resolves secrets — including cron jobs (kanban.dispatch_in_gateway: false), subprocess invocations, CLI runs, macOS launchd agents, and Docker containers — not just the interactive gateway. There are three ways to make it available, in order of precedence:

1. In ~/.hermes/.env (recommended). hermes secrets onepassword setup --token <token> writes the token to ~/.hermes/.env, exactly like Bitwarden's BWS_ACCESS_TOKEN. Because load_hermes_dotenv() always loads .env, the token is available everywhere with zero extra setup. This is the simplest reliable option.

2. In ~/.hermes/.op.env (gitignored). If you'd rather keep the service-account token out of .env — for example so .env can be checked into a private dotfiles repo while the token stays out of version control — place it in ~/.hermes/.op.env:

   bashCopy

   echo 'OP_SERVICE_ACCOUNT_TOKEN=ops_...' > ~/.hermes/.op.env
   chmod 600 ~/.hermes/.op.env
   

   Hermes auto-loads .op.env at startup, after .env, and never overrides a token already present in the environment. .op.env is gitignored so the token never enters a committed file.

3. Via systemd EnvironmentFile (Linux gateway). If you run the gateway under systemd, you can inject the token directly into the service environment:

   iniCopy

   [Service]
   EnvironmentFile=-/home/youruser/.hermes/.op.env
   

   A token injected this way takes precedence — Hermes detects that OP_SERVICE_ACCOUNT_TOKEN is already set and skips loading .op.env entirely.

If the token is reachable only through an interactive shell (op signin, OP_SESSION_* exports in .bashrc, etc.), it will not be inherited by cron jobs or freshly spawned subprocesses, and those contexts will log a warning and fall back to whatever credentials .env already held. Use one of the three options above for any non-interactive workload.

Setup

1. Install and sign in to op

Follow the 1Password CLI getting-started guide. Verify it works:

op whoami

2. Enable the integration

hermes secrets onepassword setup

This verifies op is on PATH (or use --binary-path), records your account/token settings, checks for an active session, and flips secrets.onepassword.enabled: true. Non-interactive flags:

hermes secrets onepassword setup \
  --account my.1password.com \
  --token-env OP_SERVICE_ACCOUNT_TOKEN \
  --token "$OP_SERVICE_ACCOUNT_TOKEN"

3. Map your credentials

The reference format is op://<vault>/<item>/<field>:

hermes secrets onepassword set OPENAI_API_KEY    "op://Private/OpenAI/api key"
hermes secrets onepassword set ANTHROPIC_API_KEY "op://Private/Anthropic/credential"

4. Preview and confirm

hermes secrets onepassword sync     # dry-run: resolve now, show what would apply
hermes secrets onepassword status   # config + binary + references + auth

From now on, every hermes invocation resolves the references at startup. You'll see a one-line summary in stderr the first time secrets are applied in a process.

CLI

op and 1password are accepted as aliases for onepassword.

Configuration

Defaults in ~/.hermes/config.yaml:

secrets:
  onepassword:
    enabled: false
    env:
      OPENAI_API_KEY: "op://Private/OpenAI/api key"
      ANTHROPIC_API_KEY: "op://Private/Anthropic/credential"
    account: ""
    service_account_token_env: OP_SERVICE_ACCOUNT_TOKEN
    binary_path: ""
    cache_ttl_seconds: 300
    override_existing: true

Failure modes

1Password never blocks Hermes startup. If anything goes wrong you'll see a one-line warning in stderr and Hermes continues:

Caching

Successful, complete pulls are cached in-process and on disk under <hermes_home>/cache/op_cache.json (written atomically, mode 0600), so back-to-back short-lived hermes invocations don't re-shell op for every reference. The cache:

• stores only resolved secret values — never the service-account token or any raw auth material (auth is fingerprinted into the cache key);
• is invalidated when the token, account, OP_SESSION_* variables, or the set of references change;
• is not written when a pull had any per-reference error, so a transient auth failure isn't frozen in for the TTL;
• is fully disabled — reads and writes — when cache_ttl_seconds: 0.

Security notes

• A 1Password service-account token can read every secret the account has access to. Store it in ~/.hermes/.env (not config.yaml), and revoke + regenerate from 1Password if it leaks.
• Hermes refuses to let a resolved value overwrite the token env var itself, even with override_existing: true.
• The op child process gets a minimal allowlisted environment (auth/session vars + PATH/HOME), not a copy of the full os.environ, so post-dotenv provider credentials aren't all inherited by the child.
• References are validated to start with op://, and the reference is passed after a -- option terminator so a crafted value can't be parsed as an op flag.

When NOT to use this

• Single-machine personal setups where ~/.hermes/.env is fine.
• Air-gapped environments that can't reach 1Password.
• CI/CD where an existing secrets-injection mechanism is already wired up — pick one path, not two.

The good case for this is multi-machine fleets, shared dev boxes, gateway VPSes, or anywhere you want centralized rotation and revocation across multiple Hermes installations.