Proxy

vault proxy is a slimmer relative of Vault Agent introduced in Vault 1.13. It focuses on caching and request forwarding without the templating, exec, or process-management features. Source: command/proxy.go (37k lines), config in command/proxy/config/, shared logic in command/agentproxyshared/.

Purpose

Run a local API endpoint (TCP or Unix socket) that:

• Authenticates upstream to Vault using auto-auth.
• Caches responses (with the same lease-aware cache as the agent).
• Forwards everything else to the configured Vault server cluster.

It's the "client-side proxy" use case without any of the agent's templating responsibilities.

Directory layout

command/
├── proxy.go                  # ProxyCommand
└── proxy/
    └── config/               # proxy-specific config parsing
agentproxyshared/             # the shared auth + cache code

Key abstractions

Symbol	File	Description
ProxyCommand	command/proxy.go	The CLI subcommand. Mostly mirrors AgentCommand minus templating/exec.
Config	command/proxy/config/config.go	Proxy config structs (auto-auth, cache, listener, vault).
Shared auto-auth	command/agentproxyshared/auth/	Same as agent.
Shared cache	command/agentproxyshared/cache/	Same as agent.

How it works

graph LR
    App[Local app<br/>http client] -->|HTTP/HTTPS| Proxy[vault proxy]
    Proxy -->|cached response| App
    Proxy -->|forwarded request| Vault[Vault cluster]
    Proxy -. auto-auth .-> Vault

A proxy starts an auto-auth loop, opens its listener, and serves requests by either returning a cached response or forwarding to the Vault server. The shared cache is identical to the agent's.

Why split agent and proxy?

The agent grew over time to cover too many use cases — templating, exec, caching, sink delivery — making its config dense. The proxy was carved off so workloads that only need caching/forwarding don't have to reason about templating or exec. The two share command/agentproxyshared/ exactly because their auth and cache needs are identical.

Integration points

• Same auto-auth methods as agent.
• Same cache code, including disk persistence and lease-tree invalidation.
• Receives client traffic on a configurable listener (TCP, Unix domain socket, or http_proxy_address).
• Forwards to vault.address or each cluster member.

Entry points for modification

• New cache policies: command/agentproxyshared/cache/.
• New listener type: extend command/proxy/config/.
• Anything you'd add to both: do it in agentproxyshared/, not in command/proxy.go.