pv-dotenv

Drop-in replacement for python-dotenv that resolves psamvault: placeholders at runtime.

Keep your .env files safe from AI agents. The agent sees only placeholders. Your app gets the real secrets.

Why?

# Before: secrets in plaintext — any agent reading .env can see them
DATABASE_URL=postgresql://user:password@neon.tech/db
JWT_SECRET=your-secret-key

# After: placeholders — agent sees nothing, app resolves at runtime
DATABASE_URL=psamvault:DATABASE_URL
JWT_SECRET=psamvault:JWT_SECRET

Installation

pip install pv-dotenv

Quick Start

Replace your existing dotenv import:

# Before (python-dotenv):
from dotenv import load_dotenv
load_dotenv()

# After (pv-dotenv):
from pv_dotenv import load_dotenv
load_dotenv()

Everything else stays the same. Your code reads from os.environ exactly as before.

With project scoping

If you used scan_and_protect(project_name="my-project"), pass the same name:

load_dotenv(project_name="my-project")

Without modifying os.environ

from pv_dotenv import resolve_dotenv

values = resolve_dotenv()
# → {"DATABASE_URL": "postgresql://...", "JWT_SECRET": "..."}

Override existing env vars

By default, existing environment variables are not overwritten. To force override:

load_dotenv(override=True)

How It Works

1. Reads your .env file (or custom path)
2. For each psamvault:KEY value:
   • Fetches the encrypted blob from the psamvault backend
   • Decrypts it locally using your Vault Encryption Key (VEK)
   • Sets os.environ[KEY] to the real value
3. Non-psamvault: values (like NODE_ENV=production) pass through unchanged

Auth

Path A requires no setup beyond psamvault login. Path B is for environments without a keychain (Docker, CI, servers).

Prerequisites

• Python 3.10+
• A psamvault account — pipx install psamvault and psamvault login

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

Related