DOCSEARCHbyAlgolia
Submit Docs

Agent Vault Documentation

repository·main·Indexed 23 days ago

https://github.com/infisical/agent-vault

An open-source HTTP credential proxy designed to protect AI agents from credential exfiltration. Agent Vault acts as a broker that intercepts outbound requests and injects real credentials, ensuring agents never possess sensitive keys directly. It includes support for MITM proxying, management UI exposure via Nginx, and integration templates for AI agents such as Slack bots and OpenAI Realtime WebSockets.

Tokens
83.6K
Snippets
182
Records
451
Agent score
80%

What's inside Agent Vault

  1. What is Agent Vault

    main

    Agent Vault is an open-source credential broker and proxy service designed specifically for AI agents. It sits between an AI agent and the APIs it calls (such as LLM providers, GitHub, or Stripe) to prevent credential exfiltration via prompt injection.

    Instead of giving an agent real credentials, you provide it with "dummy credentials" (e.g., __anthropic_api_key__). Agent Vault intercepts the agent's outbound HTTP/HTTPS requests, swaps the dummy credentials for real ones, and forwards the request to the target service. This ensures the agent never actually holds sensitive secrets in its environment.

  2. What is a Proposal and how does its lifecycle work?

    main

    A Proposal is a request from an agent to add, update, or remove credentials and services within a specific vault. Each proposal must be approved by a vault member with sufficient permissions for changes to take effect.

    Proposal Components

    • Services: Defines host access changes (e.g., granting access to api.stripe.com via a bearer token). Approved services are merged into the vault's service configuration.
    • Credential slots: Operations for keys that a human needs to supply, values the agent wants to store, or credentials to delete.
    • Messages: Includes a message (developer-facing) and a user_message (human-facing) for the approval UI.

    Lifecycle States

    Proposals follow a simple state machine:

    • pending → applied: Approved by a privileged vault member.
    • pending → rejected: Rejected by a privileged vault member.
    • pending → expired: The 7-day TTL (Time To Live) has elapsed.

  3. What is a Service in Agent Vault

    main

    A Service is a per-vault configuration that defines which upstream traffic agents can reach through the proxy and how Agent Vault authenticates to those targets.

    When an agent makes a request, Agent Vault matches the request against the vault's services using a host pattern. If a match is found, Agent Vault attaches the configured credentials and forwards the request.

    Matching Behavior:

    • If no service matches, the request is forwarded as plain proxy traffic by default.
    • If a vault is set to strict deny mode (unmatched_host_policy=deny in vault settings), unmatched requests are rejected with a 403 error.

    Configuration Methods:

    • Automatically: Agents can raise proposals to add or modify services, which admins then review and approve.
    • Manually: Admins can set services via the CLI using a YAML file or an interactive builder.

  4. What is a Vault in Agent Vault

    main

    A Vault is a secure logical container used to manage access to sensitive information. It serves as the central unit for organizing credentials and defining how agents interact with external services.

    Each vault consists of:

    • Credentials: Sensitive material like API keys or database credentials that cannot be extracted.
    • Services: Definitions of upstream hosts (e.g., api.stripe.com) and the specific credentials required to proxy requests to them.
    • Members: Users and agents granted access via specific roles (admin, member, or proxy).
    • Proposals: Requests from agents to use specific credentials or add new services.

    Note: A default vault is automatically created for the first user of an instance (the owner).

  5. What is Agent Vault and how does it prevent credential exfiltration?

    main

    Agent Vault is an open-source HTTP credential proxy and vault designed to sit between AI agents and the APIs they call.

    Instead of providing agents with real credentials (which risks leakage via prompt injection), you store the credentials in Agent Vault. You then configure your agents to route their HTTP requests through the proxy. Agent Vault intercepts these requests, attaches the real credentials (e.g., by substituting dummy values in headers like __anthropic_api_key__ or replacing auth headers entirely), and forwards the request to the target API.

    Key Capabilities:

    • Credential Brokering: Agents use dummy values; Agent Vault provides the real ones.
    • Pluggable Credential Stores: Use external stores like Infisical for advanced features like dynamic secrets.
    • Transparent Integration: Works with existing tools (MCP, CLI, SDK, API) by bootstrapping the agent's environment to use HTTPS_PROXY.
    • Egress Filtering: Control which agents can access specific services and endpoints.
    • Request Logging: Monitor and diagnose agent behavior by inspecting authenticated traffic.

  6. Configure URL substitutions for non-header credentials

    main

    If an API requires credentials in the URL path, query string, or request body (e.g., Telegram's /bot<TOKEN>/sendMessage), use the substitutions field in your proposal. The proxy will find a placeholder string and replace it with the real credential.

    Supported Surfaces:

    • path (default)
    • query (default)
    • header
    • body
    • websocket

    Example Configuration:

    "substitutions": [
  {"key": "TELEGRAM_BOT_TOKEN", "placeholder": "__bot_token__", "in": ["path"]}
]

  7. How agent-vault run works with Codex

    main

    The agent-vault run command performs two primary functions when used with Codex:

    1. Proxy Injection: It pre-sets HTTPS_PROXY and HTTP_PROXY environment variables, ensuring all outbound HTTP/HTTPS calls from the wrapped process (e.g., Codex) are routed through Agent Vault for credential injection.
    2. Skill Installation: It installs an Agent Vault skill at ~/.agents/skills/agent-vault-cli/SKILL.md. This skill teaches Codex how to raise proposals when it requires API access. This skill persists across sessions.

  8. Understand the Nginx Public UI Proxy architecture

    main

    The Nginx Public UI Proxy is a reverse proxy designed to expose Agent Vault's management UI (port 14321) to the public internet while keeping the MITM proxy (port 14322) isolated on a private network.

    Security Model

    • The Network is the Lock: This proxy assumes port 14322 is unreachable from the public internet (via firewall, private PaaS, or private interface). If 14322 is publicly reachable, this proxy provides no additional security.
    • Isolation: The proxy is configured with no route to 14322. It only proxies traffic to 14321.
    • Tunneling Protection: It explicitly refuses CONNECT requests with a 405 error to prevent tunneling.
    • Header Stripping: It preemptively strips X-Forwarded-User and X-Auth-Request-User headers to prevent unauthorized pre-authentication.
    • Authorization Passthrough: Unlike many proxy setups, this config does not strip the Authorization header. This is necessary because Agent Vault's management API uses Authorization: Bearer <token> for CLI and non-browser callers.

    Network Topology

    PUBLIC INTERNET                              PRIVATE NETWORK
───────────────                              ─────────────────────────────────
                                               ┌────────────────────────────┐
[browser] ─HTTPS─► [nginx reverse proxy] ────► │ Agent Vault                │
                                               │   :14321  management UI    │
                                               │   :14322  MITM proxy       │
                                               └────────────────────────────┘
                                                      ▲                 │
                                                      │ HTTPS_PROXY     ▼
                                               [agent service]   [external APIs]
                                                                  (creds injected)

  9. Understand service matching priority

    main

    When multiple service definitions match a request, Agent Vault selects a winner based on the following deterministic hierarchy:

    1. Host Tier: An exact match host always beats a wildcard host (*.example.com), regardless of path specificity.
    2. Port Specificity: Within the same host tier, a service with a defined port beats an any-port wildcard.
    3. Path Specificity: Among rules with the same host tier and port specificity, the rule with the longest literal path prefix (characters before the first *) wins.
    4. Declaration Order: If all other factors tie, the rule appearing first in the configuration list wins.

  10. How Agent Vault works

    main

    Agent Vault operates as a MITM (Man-in-the-Middle) proxy. The architecture involves two main components running on the Agent Vault server:

    1. Management UI/API (Port :14321): Used for configuration and operator access.
    2. MITM Proxy (Port :14322): Handles the actual request interception and credential injection.

    Workflow:

    1. Setup: Install Agent Vault and configure service credential substitution rules.
    2. Agent Registration: Create an "agent" in Agent Vault to obtain a unique AGENT_VAULT_TOKEN.
    3. Routing: Configure the AI agent's environment to route all outbound traffic through the Agent Vault proxy (typically via HTTPS_PROXY).
    4. Execution: The agent uses dummy credentials in its API calls. Agent Vault matches the target host against configured rules, performs the substitution, and forwards the request upstream.

  11. How vaults, credentials, and services work together

    main

    Agent Vault uses three core abstractions to manage secrets and proxy requests:

    • Vault: A named isolation boundary (e.g., prod) used to group related secrets and configurations.
    • Credential: A single secret value (e.g., ANTHROPIC_API_KEY = sk-ant-...) stored and encrypted at rest within a vault.
    • Service: The wiring for an upstream host. It defines a host pattern, an authentication mode, and substitution rules that reference credentials by name.

    Workflow: At request time, Agent Vault matches the incoming host to a Service, looks up the required Credential, and rewrites the wire bytes (headers or body) before forwarding the request to the upstream host.

  12. Configure Service Authentication Modes

    main

    When adding a Service in the Agent Vault UI, you must choose an authentication mode based on how the upstream host expects credentials:

    Bearer Authentication

    Used for services like GitHub or Notion. You provide the Token (credential key), which is the name of the credential stored in the vault (e.g., GITHUB_TOKEN). Agent Vault automatically handles the Authorization: Bearer <token> header.

    Passthrough Authentication

    Used when the credential must be injected into specific parts of the request (e.g., Anthropic or Slack). You define URL Substitutions:

    1. Placeholder: The exact string in the client request that should be replaced (e.g., __anthropic_api_key__).
    2. Surface: Where the substitution occurs (header or body).
    3. Credential: The name of the credential to inject.

    Note on Slack: For Slack, you must select both header and body surfaces because the @slack/web-api library places the bot token in the request body.