Agent

vault agent is a long-running client-side daemon that handles authentication, secret retrieval, templating, and caching on behalf of an application. Source: command/agent.go (41k lines), helpers in command/agent/ and shared logic in command/agentproxyshared/.

Purpose

The agent removes three responsibilities from application code:

1. Authentication. The agent's auto-auth loop logs in to a configured method (AppRole, AWS, GCP, JWT, Kubernetes, OCI, AliCloud, Azure, CF, Cert, KerbAuth, Token-File) and renews the resulting Vault token automatically.
2. Templating. Render Consul Template-style templates against Vault data and write them to disk (or to environment variables for an exec'd subprocess).
3. Caching. Listen on a local socket or address as a Vault-API-compatible proxy that caches responses (and optionally serves them from cache during outages).

Directory layout

command/
├── agent.go                          # AgentCommand
├── agent_generate_config.go          # vault agent generate-config helper
├── agent/
│   ├── doc.go
│   ├── *_end_to_end_test.go          # 10+ E2E tests per auth method
│   ├── exec/                         # exec mode (run a child process with env vars)
│   ├── template/                     # template mode integration
│   ├── pkiexternalca/                # external CA flows
│   ├── config/                       # agent-specific config parsing
│   └── internal/
└── agentproxyshared/                 # shared with vault proxy
    ├── auth/                         # auto-auth implementations
    ├── cache/                        # response cache & disk persistence
    └── ...

Key abstractions

Symbol	File	Description
AgentCommand	command/agent.go	The CLI subcommand; runs the agent loop until shutdown.
AutoAuth	command/agentproxyshared/auth/	Loop that authenticates and renews the resulting token.
Sink	command/agentproxyshared/sinks/	Where to deliver the auth token (file, env, etc.).
LeaseCache	command/agentproxyshared/cache/	LRU cache of token + lease responses.
Template runner	command/agent/template/	Renders Consul Template-style files using Vault data.
Exec runner	command/agent/exec/	Runs a child process with templated env vars.

How it works

graph LR
    subgraph "vault agent process"
        AA[Auto-auth method<br/>approle/aws/jwt/...] -->|renewable token| Sink[(Sink: file<br/>or env)]
        AA -->|token| Cache[Lease cache]
        Listener[Local listener<br/>tcp/socket] --> Cache
        Cache -->|forwarded request| Vault[Vault server]
        Vault -->|response| Cache
        Cache -->|cached response| Listener
        Tpl[Template runner] --> Cache
        Tpl --> File[Rendered file]
        Exec[Exec runner] --> Cache
        Exec --> Child[Child process<br/>env-vars or stdin]
    end

The agent never holds the master token; it uses the auto-auth method's renewable token and ages it out when it nears expiration.

Auto-auth methods

Implementations live under command/agentproxyshared/auth/<method>/:

• alicloud, approle, aws, azure, cert, cf, gcp, jwt, kerberos, kubernetes, oci, pcf, token-file.

Each method implements the auth.AuthMethod interface (in command/agentproxyshared/auth/auth.go) which returns the path, header, and data to send to auth/<mount>/login. The auto-auth loop handles retry/backoff and forwards the resulting token to the configured sinks.

Caching

command/agentproxyshared/cache/ contains a request cache that:

• Keys on auth identity + path + parameters.
• Persists to disk (encrypted with the agent's auth token) so a restart doesn't lose state.
• Tracks lease relationships so revoking a parent revokes children.

Implementation details are in cache_end_to_end_test.go and the cachememdb package.

Templating and exec

The agent embeds Consul Template syntax to render files from Vault data:

template {
  source      = "/etc/app/db.conf.tpl"
  destination = "/etc/app/db.conf"
}

exec mode runs a child process with templated environment variables, restarts it on changes, and shuts down the agent when the child exits.

Self-healing

agent_auto_auth_self_heal_test.go exercises the agent's behavior when the auth token is revoked out from under it: the auto-auth loop notices the failure and re-authenticates.

Integration points

• Talks to a Vault cluster over the public API.
• Shares cache and auth code with proxy via command/agentproxyshared/.
• Ships its own config grammar (command/agent/config/) parallel to the server's.

Entry points for modification

• New auto-auth method: add a package under command/agentproxyshared/auth/<name>/ implementing auth.AuthMethod, then register it in command/agentproxyshared/auth/auth.go.
• New sink: add to command/agentproxyshared/sinks/.
• Tweak cache behavior: command/agentproxyshared/cache/lease_cache.go and cachememdb/.
• New template/exec features: extend command/agent/template/ or command/agent/exec/.