enveloper

Background

[ KrebsOnSecurity, DockerHub/GitGuardian, Toyota/GitGuardian]

---

When developing software, there are often secrets that every developer or team need to deal with. These include:

• API keys
• API secrets
• Web passwords
• User-Ids
• User and Administrative Passwords
• Tokens
• Private endpoints
• File paths
• Universal Identifiers
• Authorization keys
• etc.

In some cases, these are inadvertently hard-coded into code, which is then pushed out to shared repositories. There are services to scan for these, but a recommended practice has been to place these in .env files.

[GitGuardian]

---

A Different Approach

.env files open up a new range of problems:

• If you move to a new machine, or want others to work on the code, they need to get a copy of the .env file so they can use these shared secrets.
• Over time, multiple .env files end up proliferating all over one's computer, end up in logs, backups, or get lost.
• AI-based agents with access to the local filesystem can create problems. Security company Wiz noticed that "AI-related secret instances constitute a disproportional majority of the findings (4 out of top 5 secrets found were AI-related)".

File-based .env files are best to be avoided.

---

Enter enveloper

enveloper allows you to avoid .env files or hard-coded credentials by storing secrets in your own protected system keychain. These can be injected into a build session at runtime, without any risk of inadvertent release.

Local keychains work well for individuals. But what about sharing secrets? Fortunately, cloud-based services have already solved this problem, by offering Secret Managers or Vaults stored in cryptographically secure locations.

enveloper lets you store all your secrets in your local keychain or cloud-based secret managers, and easily move them back and forth or share them without having to leave any data in the open.

Manage environment secrets via your system keychain or cloud secret stores. Don't leave exposed .env files laying about your filesystem.

---

Installation

pip install enveloper            # CLI only (scripts, Make, Docker, CI)
pip install enveloper[sdk]       # CLI + SDK — recommended for Python apps (load_dotenv / dotenv_values)
pip install enveloper[all]        # CLI + SDK + all cloud backends

For Python applications that load secrets at runtime (keychain or cloud), install the SDK extra: pip install enveloper[sdk].

Examples: Runnable samples for Docker, Makefile, Kubernetes, CI/CD, shell scripts, GitHub Secrets, the Python SDK, and domains/versioning are in the examples folder.

Quick Start

# Sample .env file

# Import an existing .env file into the keychain
enveloper import sample.env --domain dev --project Enveloper

Keys are stored in local keychain.

# List what's stored

enveloper list key --domain dev --project Enveloper

# Load local environment settings from keychain

eval "$(enveloper --domain dev --project Enveloper export --format unix)"

# Values are loaded into local environment variables. 
# Use in Makefile, shell scripts, etc. 
# 'unix' format works for Linux, Mac, and Windows WSL. 
# For Windows Powershell, use 'win' as format.

# When done, you can use 'unexport' command to remove the set of env variables

eval "$(enveloper --domain dev --project Enveloper unexport --format unix)"

# Push to cloud service

enveloper --domain dev --project Enveloper push --service aws

In the console, we can verify that the values are stored (in the case of AWS, in the SSM Parameter Store)

# Verify that they got pushed in AWS console for System Store > Parameters

enveloper list key --domain dev --project Enveloper --service aws

# Pull from AWS SSM into local keychain

enveloper pull --domain dev --project Enveloper --service aws

# Clear environment settings
enveloper clear --domain dev --project Enveloper --service aws

Multiple cloud services

Amazon Web Services (aws)

Google Cloud (gcp)

Microsoft Azure Cloud (azure)

Hashicorp Vault (vault)

Features

• Backward compatible with .env files.
• Store values in local keychains (Mac, Linux, Windows), or cloud service secret stores (see below).
• Work with individual environment variables or sets.
• Versioning of environment values using Semantic Versioning.
• Use in build chains (Make, Gradle, etc.) or CI/CD, including Github Actions.
• Support for hierarchical settings via domain and project sets.
• Shared sanitization for keys, values, and file paths before secrets are persisted or exported.

Supported Backends

Backend	Description
Local Keychain	MacOS Keychain, Linux Secret Service, Windows Credential Locker
File	Plain .env files
AWS SSM	AWS Systems Manager Parameter Store
Vault	HashiCorp Vault KV v2
GCP	Google Cloud Secret Manager
Azure	Azure Key Vault
Alibaba	Alibaba Cloud KMS Secrets Manager (untested)
GitHub	GitHub Actions secrets (coming soon)

Documentation

• Step-by-Step Tutorial - From sample.env to keychain, builds, and cloud
• Examples - Docker, Makefile, Kubernetes, CI/CD, shell, GitHub Secrets, SDK, domains/versioning
• CLI Reference - All commands and options
• Technical Details - Architecture and internals
• Local Keychain - OS keychain setup and usage
• Cloud Storage - Cloud service configuration
• Cloud Setup Guide - Azure, GCP, and AWS setup (credentials, IAM/RBAC, testing)
• Versioning - Semantic versioning for secrets
• Domains, projects & versioning - Organize secrets by domain, project, and semver
• JSON/YAML - Import/export in JSON and YAML formats
• SDK - Python SDK for load_dotenv / dotenv_values
• Project Config - .enveloper.toml configuration
• Config/Env Overrides - Priority order for settings
• Service Backend - Backend selection and configuration
• CI/CD Integration - GitHub Actions, CodeBuild, GitLab CI
• GitHub Secrets - Push keychain values into GitHub Actions secrets
• Makefile Integration - Build system integration
• Other Projects - Comparison with similar tools
• Development - Contributing and development
• LLM / AI assistant guide - Information for LLMs and AI assistants working on this repo (see also LLM/)
• MCP server - Expose enveloper secrets to other LLMs (Cursor, Claude Desktop) via Model Context Protocol
• Adding Stores - Creating custom store plugins
• Publishing - Publishing to PyPI
• Security - Secure data storage and access control
• Disclosures - Disclosures and confessions
• License - AGPL-3.0-or-later

License

GNU AGPL v3.0 or later