hermes - 💡(How to fix) Fix [Feature]: Add Infisical as an External Vault backend (sub-issue of #3630)

Problem or Use Case

Parent

Sub-issue of #3630 (Phase 4 — External Vaults), echoing @chaleic's "plugin ecosystem for secret managers" suggestion in #1583.

Problem

Phase 4's current External Vault list (HashiCorp Vault, AWS Secrets Manager, 1Password CLI, Bitwarden CLI) is missing the option that's most relevant to the local-first / self-host audience that overlaps Hermes' user base: Infisical.

When users self-host Infisical with the recommended layout (one project per service or environment, scoped via Machine Identities), Hermes today has no native path to consume those secrets. The only workarounds are external shell wrappers that hard-code a single project ID, or consolidating all secrets into one flat project — which defeats the point of the multi-project layout.

Use case (homelab / small org)

A realistic deployment to ground the design discussion:

• ~13 services, each with its own Infisical project (a chat gateway, a code forge, a knowledge base, a NAS, internal web apps, a mail relay, etc.) — exactly the layout Infisical recommends.
• One Machine Identity (e.g. hermes-agent) scoped as viewer on N relevant projects, no global org access.
• Hermes needs to read e.g. a Matrix access token from the chat-gateway project AND a Forgejo token from the code-forge project AND an SMTP password from the mail project — within the same agent session.
• Today, the typical workaround is shell wrappers that hard-code a single INFISICAL_PROJECT_ID and force users to maintain N parallel wrappers, or to re-source env files mid-session. This pattern is everywhere in the self-hosted Infisical ecosystem and is exactly what a native Hermes integration would replace.

Proposed Solution

Why Infisical specifically

1. The default open-source choice for self-hosted secret management. HashiCorp Vault moved to BSL in 2023, leaving Infisical (MIT-licensed core, fully self-hostable, supported via Docker / Helm / All-in-One) as the de-facto open-source alternative. r/selfhosted, awesome-selfhosted, and the broader homelab community have largely settled on it.

2. User-base overlap. Hermes is positioned as local-first (~/.hermes/.env, no required cloud dependency, gateway profiles run on the user's own infra). The exact users who want Hermes locally are the exact users who self-host Infisical. The two products ship to the same audience.

3. Multi-project is canonical for Infisical, not exotic. Infisical's documentation explicitly pushes "one project per service or environment" with Machine Identity-based RBAC. An integration that only handles a single INFISICAL_PROJECT_ID undermines most of the security model — it forces users to either (a) consolidate their secrets into one flat project (anti-pattern, defeats least-privilege), or (b) limit the agent's access to a single service's secrets.

4. Feasibility is already proven.

   • Varlock has a working Infisical plugin (referenced in #1583).
   • Infisical maintains an official Python SDK.
   • Universal Auth (Machine Identity) is a single REST call to obtain an access token, which is then scoped to N projects via standard RBAC. No bespoke crypto, no client-side state to manage beyond a TTL cache.
   • Rough estimate: ~200 LOC for a backend skeleton plus tests against Infisical's Docker dev image.

5. Cost-of-now-vs-later. Adding Infisical at Phase 4 design time is cheap. Adding it after a single-vault interface ships either requires retro-fitting multi-backend (likely a refactor of the secrets module) or asking users to self-patch their wrappers. The earlier this is folded in, the less interface debt later.

Proposed API (sketch — open for design discussion)

Conceptual config (in a future secrets.yaml, or extending ~/.hermes/config.yaml):

secrets:
  backends:
    - type: infisical
      host: https://infisical.example.com
      auth: universal_auth   # reads INFISICAL_CLIENT_ID + INFISICAL_CLIENT_SECRET from env
      environment: prod
      projects:
        - id: <project-uuid-1>
          alias: chat
        - id: <project-uuid-2>
          alias: forge
        - id: <project-uuid-3>
          alias: mail

The agent then addresses secrets via a namespaced key, e.g. chat:MATRIX_ACCESS_TOKEN. The backend transparently routes to the right project, handles token caching (~2h TTL on Infisical access tokens), and surfaces a clean error if a project is unreachable.

This pattern (backend-with-multiple-scoped-namespaces) generalizes to other multi-tenant vaults: HashiCorp Vault namespaces, 1Password vaults, AWS Secrets Manager paths, etc. So the surface area added to the secrets module isn't Infisical-specific, even though the first concrete implementation is.

Acceptance Criteria (proposed)

• secrets.backends[].type: infisical recognized in config schema and validated
• Universal Auth (Machine Identity) login flow implemented; access token cached with TTL and refreshed on expiry
• Multi-project resolution via aliases — agent can request a secret by <alias>:<key> and the backend picks the correct project
• Backward-compatible fallback to INFISICAL_PROJECT_ID env var (single-project mode) for setups already using a flat layout
• Integration tests against Infisical's docker-compose dev image
• Documentation page at /docs/secrets/backends/infisical.md
• Redaction (agent/redact.py) verified to mask values returned by this backend, same as for plaintext .env

Offer

Happy to prototype this once Phase 3 (#3629) lands and the External Vault interface is settled — or earlier as a draft PR if maintainers want to influence the interface design ahead of time. I operate an Infisical multi-project deployment in production daily and can pressure-test the implementation against real-world Machine Identity / RBAC edge cases (project membership changes, secret reads across project boundaries, token TTL expiry mid-session, etc.).

References

• #410 — Umbrella secrets-management issue
• #3630 — Phase 4 (External Vaults) — direct parent
• #1583 — Varlock proposal; comment by @chaleic suggesting a plugin ecosystem with Infisical mentioned
• Infisical — open-source self-hostable secret manager
• Infisical Python SDK — official, MIT-licensed

Alternatives Considered

• HashiCorp Vault (already listed in #3630): the historical default, but its move to BSL in 2023 has pushed the open-source community to seek alternatives.
• 1Password CLI / Bitwarden CLI (already listed in #3630): excellent for individual developers, but less common in homelab/small-org self-hosted setups where a centralized API-driven vault with RBAC is the natural fit.
• AWS Secrets Manager (already listed in #3630): cloud-only, doesn't fit Hermes' local-first deployment model for users who run on-prem.
• Varlock launcher (#1583): already supports Infisical as a plugin and would work today as a stopgap. However, a launcher-level wrapper means Hermes treats injected env as opaque — it can't participate in the secrets resolution lifecycle (TTL refresh, scoped routing, redaction guarantees). A native Hermes backend keeps these concerns in-process and avoids the Node dependency for users who don't otherwise need it.
• Custom shell wrappers around infisical-cli (the current de-facto pattern): works, but doesn't scale past one project per wrapper, and offloads token caching, error handling, and redaction to hand-written shell.

Feature Type

Configuration option

Scope

Large (new module or significant refactor)

Contribution

• I'd like to implement this myself and submit a PR

Debug Report (optional)