KeyZero with HashiCorp Vault

HashiCorp Vault is the standard infrastructure secret store for production environments. KeyZero integrates with Vault's KV v2 engine, giving you runtime secret resolution with added capabilities that Vault alone does not provide -- blind mode for AI agent workloads, shell-based developer ergonomics, and MCP server integration for agentic toolchains.

How the Integration Works

KeyZero connects to Vault over its HTTP API. When a secret is requested, KeyZero sends a GET request to {vault_address}/v1/{path} with the X-Vault-Token header. It expects the KV v2 response structure and extracts the target field from data.data.<field>.

No Vault agent or sidecar is required. KeyZero runs as a local CLI process and talks directly to your Vault server.

Prerequisites

You need a running Vault instance (self-hosted or HCP Vault) and a valid token:

# Install KeyZero
brew install getkeyzero/tap/keyzero

# Set your Vault token
export VAULT_TOKEN="hvs.your-vault-token"

Verify Vault access:

curl -s -H "X-Vault-Token: $VAULT_TOKEN" \
  https://vault.example.com/v1/secret/data/myapp/db | jq .data.data

Bundle Configuration

Define a Vault backend and attach resolvers that reference specific paths and fields within the KV v2 engine:

backends:
  vault-prod:
    type: hashicorp_vault
    address: https://vault.example.com

resolvers:
  - name: db-password
    mode: direct
    backend: vault-prod
    path: secret/data/myapp/db
    field: password

  - name: stripe-key
    mode: direct
    backend: vault-prod
    path: secret/data/myapp/payments
    field: stripe_api_key

  - name: jwt-signing-key
    mode: direct
    backend: vault-prod
    path: secret/data/myapp/auth
    field: signing_key

The path must be the full KV v2 API path, including the data/ segment (e.g., secret/data/myapp/db, not secret/myapp/db). The field is the key within the secret's data payload.

Running with Vault Secrets

# Direct mode -- secrets injected as env vars
kz run -- node server.js

# Blind mode -- AI agents get opaque tokens
kz run --blind -- python agent.py

What KeyZero Adds on Top of Vault

Vault handles storage, access control, and audit logging. KeyZero operates in the resolution and delivery layer, adding capabilities that complement Vault rather than replace it.

Blind Mode

Vault's API returns the raw secret value to the caller. When the caller is an AI agent, this means the LLM context window, tool call logs, and agent memory all contain the real credential. KeyZero's blind mode intercepts this: the agent receives an opaque kz_masked_* token, and a local MITM proxy swaps it for the real Vault-sourced credential on outbound HTTP requests. The secret never enters the agent's address space.

Shell Hooks

With KeyZero's shell integration, secrets auto-load when you cd into a project directory:

# Secrets from Vault are available immediately
cd ~/projects/myapp
echo $DB_PASSWORD  # Resolved from Vault, no manual export needed

This eliminates the need for wrapper scripts or .envrc files that call vault read.

MCP Server Integration

KeyZero can run as an MCP (Model Context Protocol) server, letting AI agents request secrets through a structured tool interface instead of relying on environment variables:

kz server start --mcp

The MCP server resolves secrets from Vault (and other backends) while enforcing policies and supporting blind mode -- giving AI agent frameworks a first-class secret resolution channel.

CEL Policy Enforcement

Vault policies control who can read a path. KeyZero adds a second policy layer evaluated at resolution time using CEL expressions against JWT-verified identities:

policies:
  - name: prod-db-restricted
    match:
      resource: db-password
    rule: 'identity.env == "production" && identity.service in ["api-server", "worker"]'

This is useful when multiple services share a Vault token (common in Kubernetes) but you need finer-grained control over which service gets which secret. For more on this pattern, see policy-based access control for machine identities.

When to Use Vault Directly vs. Through KeyZero

Use Vault directly when your consumers are traditional server applications with well-controlled I/O, and you already have Vault Agent or CSI Provider integrated into your deployment pipeline.

Use KeyZero with Vault when any of these apply:

• You run AI agent workloads that should not see raw credentials (blind mode)
• You want shell-level developer ergonomics without Vault CLI wrapper scripts
• You need to combine Vault secrets with other backends (1Password, AWS Secrets Manager, macOS Keychain) in a single resolution flow
• You want MCP server integration for agentic AI frameworks
• You need an additional policy layer based on JWT identity and CEL expressions

The two tools are complementary. Vault remains the source of truth for secrets. KeyZero handles last-mile delivery with protections designed for AI-native and multi-backend environments. For a detailed look at how KeyZero's resolution pipeline connects to backends like Vault, read the KeyZero architecture deep dive. If you need to unify Vault with cloud-native stores, see the AWS Secrets Manager integration. For help choosing the right approach, consult the secret management for AI agents decision guide.