Secret Source Plugins
Secret Source الإضافات
Start with meaning, then move to detail.
This lesson explains Secret Source Plugins as part of Hermes internals and extension points. You will learn what it does, when it matters, and the smallest safe test that proves it works.
If you are new, do not memorize names. Focus on three questions: what problem does this solve, what access does it need, and how can you verify the result?
For practice, inspect the first example, identify its effects, run it on test data, and compare the result with the source claim.
For advanced readers, inspect What the framework owns vs. what you own, Directory structure, The SecretSource ABC, then verify failure modes and version compatibility.
Know Python, Git, and basic project structure before changing code.
A clear outcome before you read.
- Understand Secret Source Plugins without assumed prior knowledge.
- Separate the source description from what still needs testing in your environment.
- Read the first command and identify its inputs and outputs before copying it.
How to build a secret-manager backend plugin for Hermes Agent
What does the source say, and in what order?
- 01What the framework owns vs. what you own
Start here to understand the core idea or structure.
- 02Directory structure
Read this after the foundation, then connect it to the previous step.
- 03The SecretSource ABC
Read this after the foundation, then connect it to the previous step.
- 04Contract rules (enforced, not suggestions)
Read this after the foundation, then connect it to the previous step.
- 05Choosing your shape
Read this after the foundation, then connect it to the previous step.
- 06Optional hooks
Read this after the foundation, then connect it to the previous step.
- 07Subprocess safety: use runsecretcli()
Read this after the foundation, then connect it to the previous step.
- 08Registering
Read this after the foundation, then connect it to the previous step.
- 09Users configure it like any other source
Read this after the foundation, then connect it to the previous step.
- 10Validate with the conformance kit
Finish here to verify the result and special cases.
Copy only after you understand the effect.
~/.hermes/plugins/my-vault/
├── plugin.yaml # name, description
└── __init__.py # SecretSource subclass + register(ctx)### Contract rules (enforced, not suggestions)
- **`fetch()` never raises.** Errors go in `result.error` + `result.error_kind`. A raising fetch is contained by the orchestrator and reported as `INTERNAL` — a contract violation, not a feature.
- **`fetch()` never prompts.** Startup runs in non-TTY contexts (gateway, cron, Docker). `run_secret_cli()` closes stdin so a prompting helper fails fast. Interactive auth belongs in your CLI setup flow, never on the startup path.
- **Sync, within budget.** The orchestrator enforces a wall-clock timeout (default 120s, user-tunable via `secrets.<name>.timRegistration is rejected (with a log warning, never a crash) for: non-`SecretSource` instances, invalid/duplicate names, a `scheme` another source owns, wrong `api_version`, or a `shape` outside `mapped`/`bulk`.
:::note Timing
Plugin discovery runs later in startup than the first `load_hermes_dotenv()` call, so a plugin source is not consulted by the very first env load of the process that discovers it. It IS consulted by every subsequently spawned Hermes process (gateway children, cron sessions, subagents). Bundled sources cover first-process bootstrap.
:::
## Users configure it like any otRead the first command and identify its inputs and outputs before copying it.
Match every command to your installed Hermes version, review the files and accounts it can reach, and use non-sensitive data for the first test. If this explanation differs from the source, the official source wins.