dotenvx for Secure Environment Variables

What this article covers

• What dotenvx is and what it’s designed for.
• How to encrypt .env files.
• How to manage secrets across different environments.
• How to integrate dotenvx with Docker, CI/CD, and local AI projects.
• Common pitfalls and best practices.

Introduction: dotenvx for secure environment variables

Unprotected .env files are a common security vulnerability. They often contain API keys, passwords, and tokens that can accidentally end up in repositories or backups. dotenvx is a modern open-source tool that encrypts .env files while keeping them easy to use. This makes it possible to version and share secrets without exposing the actual values.

For local AI projects, dotenvx is particularly useful when multiple agents, tools, or team members need access to the same configurations.

Key terms

• .env: File containing environment variables.
• DOTENV_KEY: Key for decrypting dotenvx files.
• Encryption: Encrypting the values in the .env file.
• Environment: Separate configurations for dev, staging, and prod.
• Vault: dotenvx also offers advanced management capabilities.
• CLI: Command-line tool from dotenvx.

Why dotenvx?

• Simple encryption: No more plaintext keys in .env files.
• Multiple environments: Manage dev.env, prod.env, and staging.env in parallel.
• Team sharing: Encrypted files can live in Git.
• CI/CD integration: Store the key as a secret, decrypt .env at runtime.
• No vendor lock-in: Open-source tool with the option to run locally.

Installation

dotenvx can be installed as an npm package or as a standalone tool:

npm install -g @dotenvx/dotenvx

Or without Node.js:

curl -fsS https://dotenvx.sh | sh

First encryption

In a project directory:

echo 'ANTHROPIC_API_KEY=DEIN_API_KEY' > .env

dotenvx encrypt

dotenvx creates an encrypted .env file and displays the DOTENV_KEY. Keep this key in a secure location.

Using decrypted values

DOTENV_KEY='DEIN_DOTENV_KEY' dotenvx run -- node app.js

All environment variables are available to the application as usual.

Multiple environments

echo 'ANTHROPIC_API_KEY=dev-key' > .env.dev
echo 'ANTHROPIC_API_KEY=prod-key' > .env.prod

dotenvx encrypt -f .env.dev
dotenvx encrypt -f .env.prod

At runtime:

DOTENV_KEY='...' dotenvx run -f .env.prod -- node app.js

Docker integration

FROM node:20
RUN curl -fsS https://dotenvx.sh | sh
COPY .env.vault /app/.env.vault
WORKDIR /app
CMD ["sh", "-c", "dotenvx run -- node app.js"]

Pass DOTENV_KEY as an environment variable at startup.

Git and backups

Encrypted .env files can live in your repository. Keep in mind:

• Commit only the encrypted file.
• Never check in DOTENV_KEY.
• Store backups of the key separately from your code, in a secure location.

dotenvx vs. secret managers

• dotenvx: Simple, file-based, good for small teams and projects.
• HashiCorp Vault / Infisical: Centralized management, rotation, dynamic secrets.

For individual applications, dotenvx is often faster to set up. With many services and teams, a dedicated secret manager makes more sense.

Common pitfalls

• Losing the key: Without DOTENV_KEY, values cannot be recovered.
• Committing unencrypted .env: Only commit the encrypted version to Git.
• Printing the key in logs: Never output DOTENV_KEY.
• Loading the wrong file: Double-check the -f parameter.
• Relying on encryption alone: Also consider access controls and backup security.

Further resources

• BotServ.de Environment Variables
• BotServ.de Secret Management
• BotServ.de HashiCorp Vault
• BotServ.de Infisical

FAQ: dotenvx

Is dotenvx free? Yes, the open-source version is free.

Can I use dotenvx without Node.js? Yes, there’s a standalone script.

What happens if I lose the DOTENV_KEY? The values are unrecoverable without the key.

Should I commit encrypted .env files to Git? Yes, that’s one of its benefits. But never include the key in the repository.

Is dotenvx a full secret manager? No, it’s a simple encryption and loading tool. Vault or Infisical are better suited for complex scenarios.

Sources and further reading

• dotenvx: https://dotenvx.com/
• dotenvx Docs: https://dotenvx.com/docs/
• dotenvx GitHub: https://github.com/dotenvx/dotenvx

Summary: dotenvx for secure environment variables

dotenvx is a straightforward way to encrypt .env files while keeping them convenient to work with. It works well for small teams, local AI projects, and CI/CD pipelines where secrets should not be stored in plaintext in your repository. The critical factor is handling DOTENV_KEY securely: without it, your values are lost. For more complex requirements like rotation or dynamic credentials, a dedicated secret manager is the better choice.