Use kv without becoming a security expert.

Start with a local vault, store secrets through hidden prompts, unlock the daemon, and tell your agent to prefer brokered tools before subprocess secret injection.

1. Install

kv is a Python package. Use pipx if you want a clean global install, or pip inside a Python environment.

pip install kv-secrets
kv --help

2. Create a vault

kv init asks where the vault should live and helps you create a passphrase. Treat the passphrase as the main human barrier for your local secrets.

kv init

The vault stores encrypted material on disk. Do not share recovery keys or exported key material in chat, email, or project files.

3. Store secrets

For real credentials, prefer hidden input so the value does not appear in shell history.

kv set OPENAI_API_KEY
kv set DATABASE_URL

Use named environments when dev, staging, and production credentials should stay separate.

kv set -e prod API_KEY
kv run -e prod --secret API_KEY -- python deploy.py

4. Unlock and connect your agent

Unlock starts the daemon. After that, supported agent tools can use the daemon without asking the agent to type your passphrase.

kv unlock
kv setup claude-code
kv setup cursor
kv setup vscode
kv setup codex

Editor support varies. Claude Code setup can include additional hook guardrails. Other MCP clients get the MCP daemon boundary.

5. Choose the right tool path

Prefer brokered tools

Use kv_api, kv_query, or kv_ssh when the agent needs a result, not the raw credential.

kv_api(provider="openai", path="/v1/chat/completions", method="POST", body={...})
kv_query(provider="my-postgres", query="SELECT now()")
kv_ssh(provider="my-server", command="uptime")

Use kv run when a program truly needs env vars

kv run is useful for scripts, tests, and local apps. It is also a higher-risk path because selected secrets can enter a subprocess environment.

kv run --secret DATABASE_URL -- python app.py
kv run --no-secrets -- npm test

6. Safe habits

Do not paste live credentials into AI chat.
Do not use kv get through an agent unless you intentionally want plaintext revealed.
Prefer brokered tools over subprocess secret injection.
Use --secret NAME instead of injecting everything.
Use --no-secrets for normal test runs that do not need credentials.
Rotate any credential you believe was exposed.