mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-07-11 13:41:53 +00:00
b24ff550c3
* docs(secrets): secret-source plugin developer guide + sidebar registration for 1Password page - New developer-guide/secret-source-plugin.md: SecretSource contract (never raises/prompts, fetch-only, timeout budget), framework-vs-plugin ownership table, mapped-vs-bulk shape guidance, run_secret_cli() subprocess-safety, registration + timing note, conformance kit usage, ErrorKind reference. - Register user-guide/secrets/onepassword in the sidebar (page shipped in #59498 but was not listed, so it was unreachable from nav). - Cross-link the user-guide plugin section to the new dev guide. * docs: group all plugin guides under a Plugins subcategory in Extending - Move guides/build-a-hermes-plugin.md -> developer-guide/plugins/index.md (both locales) and make it the category landing page (slug pinned to /developer-guide/plugins). - New sidebar subcategory Developer Guide > Extending > Plugins holding the general guide + all 8 provider-plugin docs (llm-access, memory, context-engine, secret-source, model, image-gen, video-gen, web-search); provider-doc URLs unchanged. - Client redirect /guides/build-a-hermes-plugin -> /developer-guide/plugins. - Update 30 cross-links across both locales.
34 lines
2.7 KiB
Markdown
34 lines
2.7 KiB
Markdown
# Secrets
|
|
|
|
Hermes can pull API keys from external secret managers at process startup instead of storing them in `~/.hermes/.env`. The bootstrap token for the secret manager lives in `.env`; every other provider key (OpenAI, Anthropic, OpenRouter, etc.) can stay in the manager and rotate centrally.
|
|
|
|
Supported:
|
|
|
|
- [Bitwarden Secrets Manager](./bitwarden) — `bws` CLI, lazy-installed, free tier works.
|
|
- [1Password](./onepassword) — `op://` references via the official `op` CLI; service-account or desktop session auth.
|
|
|
|
## Multiple sources at once
|
|
|
|
You can enable more than one secret source at the same time — for example a team Bitwarden project alongside a personal vault plugin. Sources compose per env var with a deterministic precedence ladder:
|
|
|
|
1. **Your `.env` / shell wins by default.** A source only replaces a pre-existing value when its own `override_existing: true` is set (Bitwarden defaults to true so central rotation works).
|
|
2. **Mapped sources beat bulk sources.** A source where you explicitly bind env vars to references (an `env:` map) outranks a source that injects a whole project of secrets implicitly, regardless of ordering.
|
|
3. **First source wins.** Within the same shape, the order of the optional `secrets.sources` list (or registration order) decides. Later claims on an already-claimed var are skipped — with a startup warning, never silently.
|
|
|
|
`override_existing` never lets one source overwrite a var another source already claimed, and no source can ever overwrite another source's bootstrap token (e.g. `BWS_ACCESS_TOKEN`).
|
|
|
|
```yaml
|
|
secrets:
|
|
sources: [bitwarden] # optional explicit ordering
|
|
bitwarden:
|
|
enabled: true
|
|
project_id: "..."
|
|
```
|
|
|
|
Every credential injected by a source is labelled with its origin — setup flows and `hermes model` show `(from Bitwarden)` next to detected keys so you always know where a value came from.
|
|
|
|
## Adding your own backend
|
|
|
|
Third-party secret managers ship as standalone plugins, not core PRs. A backend subclasses `agent.secret_sources.base.SecretSource` (one required method: `fetch(cfg, home_path) -> FetchResult`) and registers via `ctx.register_secret_source(MySource())` in the plugin's `register(ctx)`. The orchestrator owns precedence, conflict handling, timeouts, and provenance — your source only fetches. Full guide with the contract rules, subprocess-safety helper, and conformance kit: [Building a Secret Source Plugin](/developer-guide/secret-source-plugin).
|
|
|
|
The bundled set is deliberately closed (same policy as memory providers): Bitwarden and 1Password ship in-tree. Everything else — Infisical, Proton Pass, HashiCorp Vault, AWS Secrets Manager, OS keystores — belongs in plugin repos; share them in the Nous Research Discord (`#plugins-skills-and-skins`).
|