Agent Vault (Infisical) — Analysis for Hermes Agent Integration

Codex 核验（2026-10-09）：Checked the official README: unmatched requests are forwarded by default; strict rejection requires unmatched_host_policy=deny. Proxy use and CA trust do not themselves enforce host network isolation. The agent token still authorizes service use, so hiding upstream keys does not eliminate token theft or API abuse. The SDK creates sessions and proxy configuration; it does not hand upstream keys to the agent. The README recommends the separate Infisical product for enterprise production; this report did not validate production readiness, latency, secure memory erasure, or Hermes integration end to end. Historical stars and machine state remain snapshots.

Researched: 2026-06-06 Repository: github.com/Infisical/agent-vault (1,610 ★, Go) Docs: https://docs.agent-vault.dev License: MIT

---

1. Architecture Overview

Agent Vault is an HTTP credential proxy and vault written in Go. It sits as a MITM forward proxy between AI agents (Claude Code, Hermes, OpenClaw, custom agents) and the outbound APIs they call. It ships as a single binary that runs both a control-plane HTTP API (port 14321) and a transparent forward proxy (port 14322).

┌─────────────────────────────────────────────────────────────┐
│ Public internet                                              │
│   api.anthropic.com    api.github.com    api.stripe.com      │
│          ▲                   ▲                  ▲            │
└──────────┼───────────────────┼──────────────────┼────────────┘
           │                   │                  │
           └───────────────────┼──────────────────┘
                               │ outbound HTTPS (Agent Vault injects
                               │ real credentials on the way out)
┌──────────────────────────────┼──────────────────────────────┐
│ Private network              │                              │
│  ┌───────────────────────────┴────┐    ┌──────────────────┐ │
│  │ Agent Vault                    │    │ AI Agent          │ │
│  │ :14321  management UI / API    │◀───│ HTTPS_PROXY=      │ │
│  │ :14322  MITM proxy             │    │ agent-vault:14322 │ │
│  │  (real credentials encrypted)  │    │ (placeholders)    │ │
│  └────────────────────────────────┘    └──────────────────┘ │
└──────────────────────────────────────────────────────────────┘

Core Components

Data Flow

1. Agent sets HTTPS_PROXY=http://agent-vault:14322, HTTP_PROXY=http://agent-vault:14322
2. Agent uses a dummy placeholder value for API keys (e.g., ANTHROPIC_API_KEY=__anthropic_api_key__)
3. Agent makes an API call → traffic hits Agent Vault proxy
4. Agent Vault authenticates the agent via Proxy-Authorization header (agent token, never forwarded to upstream)
5. Matches the target host against vault’s services
6. Looks up real credential from encrypted store
7. Injects real credential into the outbound request header (or substitutes placeholders in path/body/query)
8. Forwards the request to the real upstream API over HTTPS
9. Upstream response flows back through the same connection

---

2. How Credential Brokering Works

The Core Principle: “Agents Should Not Possess Credentials”

Agent Vault’s key innovation: the AI agent never holds real API keys. The agent environment contains only:

• A revocable agent token (av_agt_...) — authenticates to Agent Vault, has no relationship to the upstream API keys
• Placeholder strings in env vars (e.g., __anthropic_api_key__) — these look like credentials but are inert

Credential Injection Mechanisms

Auth Type Injection (5 modes):

Substitution Injection: Placeholder strings in the URL path, query string, request body, WebSocket text frames, or headers are scanned and replaced at proxy time. Example:

• Service declares substitutions: [{key: TWILIO_SID, placeholder: __sid__, in: [path]}]
• Agent sends GET /2010-04-01/Accounts/__sid__/Messages.json
• Agent Vault replaces __sid__ with the real SID before forwarding

Security Architecture

Proposal Workflow (the human-in-the-loop)

Agent hits 403 on unknown host
  → Agent POSTs /v1/proposals with service request + credential slots
  → Agent Vault creates proposal, returns approval URL
  → Agent shares URL with human (e.g., in Discord/Slack/Telegram)
  → Human clicks link, reviews requested permissions, provides actual credential values
  → Human approves
  → Agent Vault merges service rules + credentials atomically
  → Agent retries original request — now it works

Credential Store Backends

• Built-in (default): SQLite database, AES-256-GCM encrypted
• Infisical (external): Polls Infisical project, encrypts locally with same DEK

---

3. Comparison with Hermes’ Current .env Approach

Hermes Current Approach

Hermes loads credentials from ~/.hermes/.env via load_hermes_dotenv() in hermes_cli/env_loader.py:

~/.hermes/.env              ~206 key=value pairs (API keys + config)
  ├── OPENROUTER_API_KEY    (primary LLM provider)
  ├── GEMINI_API_KEY        (alternative providers)
  ├── KIMI_API_KEY          
  ├── ARCEEAI_API_KEY       
  ├── HF_TOKEN              (HuggingFace)
  ├── EXA_API_KEY           (web search tool)
  ├── FIRECRAWL_API_KEY     (web crawling)
  ├── FAL_KEY               (image generation)
  ├── SLACK_BOT_TOKEN       (messaging platform)
  ├── TELEGRAM_BOT_TOKEN    
  ├── BROWSERBASE_API_KEY   (browser automation)
  ├── GROQ_API_KEY          (speech-to-text)
  ├── GITHUB_TOKEN          (skill hub)
  ├── VOICE_TOOLS_OPENAI_KEY (TTS/STT)
  ├── ... and many more

Flow: .env → python-dotenv loads into os.environ → Hermes agent process reads os.environ[KEY] at runtime → sends directly in HTTP headers/API calls.

Credential Pool: Hermes has a CredentialPool class (agent/credential_pool.py) that manages multi-credential failover for same-provider scenarios. It supports strategies (fill_first, round_robin, random, least_used), tracks exhaustion, dead credentials, and cooldown TTLs. But it still operates on raw credential values that the process already holds in memory.

External Secret Sources: Hermes has basic support for Bitwarden via _SECRET_SOURCES tracking in env_loader.py, but this is a compile-time injection into os.environ — not a runtime proxy architecture.

Side-by-Side Comparison

Security Comparison

Current .env approach vulnerabilities:

1. Prompt injection → credential exfiltration: Agent could be tricked into reading .env, printing os.environ, or including keys in output
2. Filesystem access: Processes with sufficient file permissions can read .env; same-host presence alone does not grant access
3. Hardcoded in process memory: Keys persist in Python process memory for session duration
4. No access scoping: Agent has ALL keys — can’t restrict per-host or per-task
5. No audit trail: Can’t distinguish which key was used for which request

Agent Vault mitigations:

1. Agent holds placeholders and an agent token; prompt injection can still misuse that token or authorized services
2. Agent token is revocable, vault-scoped, and grants only proxy role (cannot read credential values)
3. Credentials are decrypted for forwarding; discarding references is not proof of secure memory erasure
4. Service rules scope credential injection; deny unmatched hosts explicitly and prevent direct network bypass to enforce an allowlist
5. Full request logging on the proxy

Trade-offs

---

4. Integration Feasibility

How Hermes Would Use Agent Vault (the documented approach)

The Agent Vault docs include a specific guide titled “Run Hermes on a VPS” that walks through:

1. Provision two VPS boxes (broker + agent host)
2. Install Agent Vault on the broker
3. Create vault with credentials + services
4. Create agent token
5. On the Hermes host:
   • Install Agent Vault CLI
   • Set AGENT_VAULT_ADDR, AGENT_VAULT_TOKEN, AGENT_VAULT_VAULT
   • Set all env vars to placeholder values (e.g., ANTHROPIC_API_KEY=__anthropic_api_key__)
   • Run: agent-vault run -- hermes (boots Hermes with HTTPS_PROXY set)

This is already a fully documented, working integration path. The Agent Vault team has a companion video demonstrating this exact flow.

Integration Depth Options

Option A: Standard HTTPS_PROXY Integration (recommended, already works)

• Deploy Agent Vault on separate host
• Set HTTPS_PROXY environment variable
• Replace real keys with placeholders in .env
• agent-vault run -- hermes wrapper
• Pros: Zero code changes in Hermes, fully documented
• Cons: Doesn’t leverage Hermes-specific features (CredentialPool, credential source tracking)

Option B: Deep Integration (agent-vault-sdk / custom Python client)

• Build a Hermes plugin (plugins/agent-vault/) that:
  • Implements Hermes’ credential resolution interface
  • Mints scoped sessions and sets proxy configuration; upstream credentials remain at the broker
  • Supports the proposal workflow (proactive proposal creation when new hosts are hit)
  • Integrates with Hermes’ CredentialPool for failover
• Pros: Native Hermes experience, credential pool integration, proposal-aware
• Cons: ~2-4 weeks development effort

Option C: Minimal Integration (Hermes skill)

• Create an agent-vault skill that:
  • Mints short-lived sessions via Agent Vault SDK
  • Automates vault/service configuration
  • Provides hermes agent-vault setup wizard
• Pros: Quick to ship, can be an optional skill
• Cons: Still relies on HTTPS_PROXY under the hood

Technical Challenges

1. CredentialPool incompatibility: Hermes’ CredentialPool operates on raw credential values for failover/rotation. Agent Vault’s proxy model intentionally hides raw values. A deep integration would need an adapter layer.

2. 200+ env vars: Hermes has ~206 key=value pairs in .env. Not all are credentials — many are config (timeouts, paths, flags). Only ~40-50 are actual sensitive credentials. Each would need a corresponding service rule in Agent Vault.

3. Tools that bypass HTTPS_PROXY: Some tools/libraries may not respect HTTPS_PROXY (e.g., direct socket connections, WebSocket libraries, custom transports). Agent Vault’s MITM handles CONNECT tunnels but edge cases exist.

4. ${LOCALIP} development: Running Agent Vault locally can work (agent-vault server -d) but the security guarantee requires separation. On a single machine, the agent process could still access the Agent Vault process if not properly sandboxed.

5. Proposal UX: The proposal workflow (agent asks human for credential approval via link) is powerful but adds friction. Hermes currently uses pre-configured keys — the friction of explicit approval every time a new service is needed may not suit all workflows.

What Would Need to Change in Hermes

For Option A (proxy-only):

• Install script: add Agent Vault installation step
• CLI: add hermes agent-vault setup command to create vault/agent token
• .env example: document placeholder mode
• Documentation: add Agent Vault integration guide

For Option B (deep integration):

• New plugin: hermes-agent/plugins/credential-store/agent-vault/
• Modify env_loader.py: add Agent Vault as a credential source (alongside Bitwarden)
• Modify CredentialPool: add Agent Vault adapter that calls the agent-vault-sdk
• New proposal handler: intercept 403s from Agent Vault and auto-create proposals
• New CLI commands: hermes agent-vault subcommand for management

---

5. Concrete Recommendation

Recommendation: ADOPT — but as a GRADUAL, COMPLEMENTARY deployment option

Agent Vault does not need to replace Hermes’ .env system. It should augment it as an alternative deployment mode for users who want stronger credential security guarantees. Both approaches can coexist.

Implementation Plan

Phase 1 — Document & Enable (1-2 days)

• Add Agent Vault as an optional skill/plugin
• Create hermes agent-vault setup wizard
• Update .env.example with placeholder documentation
• Add integration guide to Hermes docs

Phase 2 — Proxy Integration (already works out of the box)

• Test and verify agent-vault run -- hermes end-to-end
• Document the two-VPS architecture
• Add Docker Compose example for local evaluation

Phase 3 — Deep Integration (2-3 weeks, optional)

• Build plugins/credential-store/agent-vault/ Python client
• Agent Vault-aware credential resolution in env_loader.py
• Proposal workflow integration (automatic proposal creation on unknown hosts)
• CredentialPool adapter for Agent Vault-backed failover

Phase 4 — Advanced (future)

• Short-lived session minting via agent-vault-sdk for ephemeral sandboxes
• Policy-as-code: define Hermes per-session service permissions in Agent Vault

When to Use Agent Vault vs .env

Key Judgment

Agent Vault has an official proxy integration design; production readiness and the proposed Hermes integration have not been tested here. Its README distinguishes this self-contained project from Infisical Agent Vault, which it recommends for production and enterprise use. The licensing statement also reserves an enterprise ee exception. The fundamental architecture is sound: proxy-based credential injection is the right security pattern for AI agents, addressing the prompt injection credential exfiltration problem that .env cannot solve.

The critical insight: Agent Vault does not compete with Hermes’ .env system — it complements it. The .env remains the simplest on-ramp for local development. Agent Vault becomes the production security layer when credentials must be protected from the agent itself.

For Hermes as an open-source project, offering both options is a differentiator: users can start with .env and graduate to Agent Vault as their deployment matures.

Verdict

Bottom line: Agent Vault should become a FIRST-CLASS deployment option for Hermes, alongside the existing .env mode. Make it easy to opt in, document both paths clearly, and build deeper integration over time. Do NOT force migration — offer choice.