kvsecure

Let agents use credentials without handing them the raw keys.

kv stores secrets in a local encrypted vault. Your agent asks kv to use a credential for a specific job. The safer brokered tools make the call and return the result, not the secret.

Install kv See the flow
Local encrypted vault Passphrase unlock Brokered API calls Open source
credential boundary demo kv mode: only request and result cross the boundary
AI agent reads, runs, retries Powerful, but not a vault boundary.
Plain secret sk_live_**** .env, chat paste, log, or script input.
Process env / stdout / files The raw value can spread after handoff.
Provider API response The work succeeds, but the key travelled.
Agent sees raw path residue Output, logs, files, and retries can carry traces.
Weak boundary: the raw secret becomes available to the agent path or subprocess path.
AI agent requests work Can ask for a provider call, query, or SSH action.
kv broker raw key stays here
sealed key sk_live_****
Provider API / DB / SSH Receives the credentialed request from kv.
Agent receives useful result Response body, query rows, command output.
Better boundary: the agent gets the result. The raw secret remains inside the kv-controlled path.

kv is for the exact moment where an AI coding agent needs to touch real infrastructure, but you do not want to paste keys into chat, context, logs, or random scripts.

The old pattern is too loose for agentic work.

Traditional developer secret handling assumes the developer is driving every command. AI-assisted work changes that. The agent can write code, run commands, inspect files, and retry. Secrets need a clearer boundary.

.env

Plain files get read.

If an agent can inspect the project, plaintext secrets are just another file.

Chat

Pasted keys become history.

Once a key is in a conversation, you are now managing exposure, not access.

SDK

Plaintext return values spread.

If a tool returns the secret to the agent, it can leak into output, logs, or generated files.

The safer path is brokered use.

The core idea is simple: the agent requests an action. kv performs the credentialed part inside the daemon. The agent receives the useful result.

01

Brokered API, query, and SSH tools

Use this whenever possible. kv_api, kv_query, and kv_ssh keep raw credentials in the daemon request path instead of returning them to the agent.

kv_api(provider="openai",
       path="/v1/chat/completions",
       method="POST",
       body={...})
02

Scoped command runs

Use kv run for programs that genuinely need environment variables. It is useful, but higher risk than brokered tools because a subprocess can receive selected secrets.

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

The product is six small engines working together.

Each engine exists to keep the user in control while still letting agents do real work.

Vault

Encrypted local storage

Secrets are stored encrypted on disk. The vault is meant to be usable by normal developers, not only security teams.

Unlock

Human approval barrier

The user unlocks the vault with a passphrase, with optional 2FA for stronger local control.

Broker

Credentialed work without raw handoff

Brokered tools let the daemon use credentials on behalf of the agent without returning the raw value.

Scope

Only what the job needs

Selected secret runs and capability paths reduce unnecessary credential exposure.

Audit

Inspectable usage trail

Usage is designed to be reviewable so teams can understand what happened later.

Guide

Agent instructions that prefer safer tools

Editor setup can teach agents to use brokered paths first and risky paths only when needed.

Trust comes from clear boundaries, not magic claims.

kv improves the secret-handling path. It does not make every possible script safe.

What kv is designed to protect

  • Secrets sitting in plaintext project files.
  • Raw keys being pasted into AI chat.
  • Agent workflows that only need API/query/SSH results.
  • Accidental exposure during normal local development.

Where users still need care

  • kv run can pass selected secrets to a subprocess.
  • A malicious script can still try to exfiltrate data if you approve a risky run.
  • Weak passphrases and unsafe credential sharing remain user risks.
  • Team/cloud sync is not a public production feature yet.

Start with one install and four kv commands.

Use the hidden prompt form for real secrets. Avoid putting live keys directly into shell history.

pip install kv-secrets
kv init
kv set OPENAI_API_KEY
kv unlock
kv setup claude-code

Trust should be inspectable.

kv keeps its public claims narrow: local first, open source, documented boundaries, brokered tools preferred, and team features marked as future work until production evidence exists.

Source on GitHub Security policy PyPI package Human guide

Team vaults are next, not advertised as done.

The local product is the launch surface. Team sync, roles, and managed sharing should stay in private beta language until the backend and security model are ready.

Join the team beta list