Improving .env-Based Workflows with KeePass (Cloud-Free, If You Want)

Photo by Christopher Gower on Unsplash

Introduction

With the rise of the Twelve-Factor App methodology, configuration became strictly separated from code.

Golden Rule: It should be possible to open-source a project at any moment without exposing secrets.

Secrets are injected from the environment in the form of environment variables. They are language agnostic, not cheked into Git and you can scale from local to production without changing a single line of code.

Exporting a multitude of variables every time you want to build or start a project can be tedious. The [dotenv](https://www.npmjs.com/package/dotenv)library for JavaScript came to the rescue. The library loads a .env file at the app's startup. The file is a simple text file with lines in the KEY=VALUE format that are loaded into the process's memory. The .env file is not checked into Git; it stays on the local disk and is managed by each individual developer. Libraries similar to [dotenv ](https://www.npmjs.com/package/dotenv)are available for various programming languages.

The Problem

Storing all required configuration variables, including secrets, in a local .env file is very common. Although this is a broadly accepted practice, it presents the following drawbacks:

1. Danger of Git Leaks: When a developer forgets to add the .env file to their .gitignore, it can be accidentally pushed to GitHub. All contained secrets are then compromised forever.
2. Shared Secret Mess: There is no easy way to share secrets with teammates. New team members often receive a copy of a colleague’s .env file over an insecure channel. These distributed .env files tend to get out of sync; after a git pull, you might be surprised by a "variable missing" error simply because your .env file is not up-to-date.
3. Production Misunderstanding: Secret management for production is a solved problem, but some developers try to implement .env file-based procedures in production environments. In production, secrets should exist only in memory and not sit as a plain-text file on a disk.

The Solution

Fortunately, there are many products available to help you move away from secrets in your .env files. Here is a certainly incomplete list of products:

• Managed cloud secrets: AWS Secrets Manager, Google Secret Manager, Azure Key Vault
• Developer‑focused: Doppler, Infisical, dotenv-vault, varlock
• Self‑hosted / enterprise‑grade: HashiCorp Vault
• GitOps / encrypted files: Mozilla SOPS, git-crypt
• Kubernetes-specific: Sealed Secrets
• Password manage integration: 1Password Secrets Automation

Some of these products encrypt .env files, some completely eliminate the idea of injecting secrets via environment variables, while others offer managed or self-hosted cloud services for online synchronization of secrets.

In this article, I will present two relatively new solutions that take a step back and implement a simpler approach to the problem directly on your local development machine. Both make use of the wonderful KeePass open-source password manager ecosystem. There ist No shortage of Projects exploring similar ideas - feel free to Check them out too.

Keeenv (Python)

[embed]keeenv — populate env vars from KeePass Originally published at https://stephencross.site on August 17, 2025.medium.com

Keeenv is a small CLI utility that populates environment variables from a KeePass (KDBX) database, extracting secrets only when required and avoiding plain-text .env files in source control.

Primary Goal: To make it easy and secure to run tools that expect environment variables while keeping credentials encrypted in a single source of truth.

Key Features

• KeePass Integration: Reads entries and attributes from a KeePass database (using the path and optional keyfile declared in .keeenv).
• On-demand Injection: Supports two main modes — keeenv run <command> to execute a command with secrets available as environment variables, or eval "$(keeenv eval)" to populate the current shell session.
• Configuration File: Uses a .keeenv file in the project directory to define the mapping between environment variables and KeePass entries or attributes. This file can also include non-secret variables.
• Utility Commands: Includes keeenv init, keeenv add, and keeenv list to help create configurations, add credentials to the database, and list configured variable names without revealing their values.

Example

.keeenv (commited):

[keepass]
database=/home/alice/secrets.kdbx
keyfile=/home/alice/secrets.key
[env]
DB_URL = ${"Prod DB"."ConnectionString"}
API_KEY = ${"ThirdParty"."API Key"}

Run a command with secrets injected (no.env file created)

keeenv run node server.js

Or populate the shell for interactive work (temporary, in-memory):

eval "$(keeenv eval)"
# secrets available in $DB_URL and $API_KEY for this shell session only

Summary

Keeenv cleanly eliminates the primary pain points of .env workflows. By keeping secrets encrypted in a KeePass database and injecting them only at runtime, it removes the risk of accidental Git leaks and ensures the repository is always ready to be open-sourced. Teams benefit from a single, encrypted source of truth, making the sharing and updating of credentials orderly and consistent — rather than a tangle of copied .env files.

Furthermore, because secrets are injected on demand rather than persisted as plain-text, Keeenv encourages a ‘no-files-on-disk’ mindset for production workflows while fitting smoothly into local development routines. Overall, it is a lightweight, practical tool that meaningfully raises security and developer confidence with minimal friction.

DesktopSecrets (Go)

DesktopSecrets is the solution I created to address the described problems. It is an open-source project that provides a local service and command-line tools to fetch secrets for development workflows. By exposing these secrets to processes on the developer’s machine only when needed, it eliminates the need to store plain-text files in a repository.

Primary Goal: To provide developers with a convenient and secure way to access secrets on their desktop without scattering .env files or plain-text credentials across various projects. It centralizes secret retrieval for local applications while ensuring all secret values remain encrypted at rest in a local store.

Key Features

• Local Service+ CLI: Runs a background service that responds to local requests for secrets and a CLI to request or inject them into commands.
• KeePass Integration: Works with a KeePass (KDBX) database as the encrypted source of truth for secrets. For convenience, databases stay unlocked for a configurable duration before automatically re-locking. The system is flexible, allowing multiple different KeePass databases to be referenced in one .env file template
• Template Support: Supports .env file templates, allowing projects to declare and check in the required variable keys while keeping the actual secret values out of the repository.

Example

Create a .env.tpl file that contains references to secrets:

DATABASE_URL=postgresql://localhost:5432/mydb
API_SECRET=keepass($USERPROFILE\Credentials.kdbx|dev-api-secret)
LOG_LEVEL=debug

Use tplenv to output the combined content of the resolved .env.tpl file, so that the output can be sourced into the current shell.

or

Use tplenv run to run a command with the content of the resolved .env.tpl file as environment.

Conclusion

With DesktopSecrets users are only prompted once to unlock the KeePass database for a set duration. While this enhances the developer experience, this convenience feature makes it slightly less secure than a solution, which requires re-entering the password for every execution. This trade-off balances workflow efficiency with a smaller, time-limited window of exposure.