This post originally appeared on dev.to.

Most teams keep local secrets in .env.local and add that file to .gitignore. That is the bare minimum, and it does not address a more pressing risk: supply chain attacks and compromised local tooling that read .env files as soon as they get repo access.

Once a malicious dependency, postinstall script, editor extension, MCP server, AI coding tool, or other local helper can inspect your workspace, plain-text .env.local files become low-effort, high-value targets.

I wanted a low-friction way to reduce that blast radius without forcing the whole team onto a heavyweight secrets manager for day-to-day local development.

This is the pattern I landed on:

• keep non-secret local config in .env.local
• move actual secrets into .env.local.secrets
• encrypt .env.local.secrets with dotenvx
• move the decryption key out of disk and into macOS Keychain
• load .env.local first, then only decrypt secrets when an explicit opt-in flag says to

Important distinction: I am not using dotenvx the way it is often marketed, where encrypted env files are committed to the repo and shared that way. This setup is local-only. The encrypted file and .env.keys both stay uncommitted, and I prefer it that way. Committing encrypted env files is useful when you want team-wide encrypted config distribution, but that was not my goal. I wanted to reduce plaintext secrets on developer machines and raise the cost of tools that slurp local env files, while keeping the workflow simple enough that teammates actually use it.

The setup

Start with a normal .env.local, then split it:

• .env.local: safe local config, feature flags, non-secret defaults
• .env.local.secrets: secrets only

Example:

# .env.local
BETTER_AUTH_URL=http://localhost:3000
USE_KEYCHAIN_FOR_DOTX=true

# .env.local.secrets
POSTGRES_URL=postgres://...
GOOGLE_CLIENT_SECRET=...
BETTER_AUTH_SECRET=...

Make sure your .gitignore covers all the pieces:

.env.local
.env.local.secrets
.env.keys

Then encrypt the secrets file:

pnpm exec dotenvx encrypt -f .env.local.secrets

That gives you an encrypted .env.local.secrets and a decryption key in .env.keys.

At this point, you have improved at-rest security a bit, but the key is still on disk, which is not the end state we want.

Why bother with the extra steps?

There have been enough supply chain and developer tooling incidents lately that I no longer treat “it is gitignored” as a meaningful security boundary. Once something malicious lands in your development environment, one of the first profitable things it can do is read local env files and exfiltrate credentials.

Encrypting local secrets at rest is not a complete defense, but it is a useful speed bump:

• secrets are no longer sitting in plaintext on disk
• the decryption key can live in the OS keychain instead of another dotfile
• accidental repo-wide file reads become less damaging
• you can keep the workflow mostly compatible with existing frameworks

This does not protect secrets after your app starts. At runtime, the process still has decrypted environment variables in memory. But that is still better than leaving everything plaintext on disk all the time.

Move the key into macOS Keychain

Copy the DOTENV_PRIVATE_KEY_LOCAL_SECRETS value from .env.keys, then store it in Keychain:

security add-generic-password -U \
  -a LOCAL_SECRETS_DOTENVX_KEY \
  -s LOCAL_SECRETS_DOTENVX_KEY \
  -w

With security, keeping -w as the last argument makes it prompt you for the secret instead of putting it in your shell history.

The LOCAL_SECRETS_DOTENVX_KEY label is just an example. Pick any consistent Keychain item name you want, then use that same name everywhere in your scripts.

Now you can delete .env.keys. Before you do, stash the key somewhere safe outside the repo. A password manager like 1Password is a good choice. You will need it if you set up another machine or need to recover.

With that, your decryption key is no longer sitting next to the repo in another plaintext file.

Linux and Windows. This post uses macOS Keychain, but the same idea applies elsewhere. On Linux, secret-tool (backed by libsecret and GNOME Keyring or KWallet) fills the same role. On Windows, you can use Credential Manager via PowerShell’s Get-StoredCredential / New-StoredCredential cmdlets. The loading pattern stays the same; only the key retrieval command changes.

The loading pattern

The subtle part is loader order.

If you want a flag like USE_KEYCHAIN_FOR_DOTX=true to live in .env.local, your app needs to read .env.local before it decides whether to pull the decryption key from Keychain.

That means the loader should do this:

1. Load .env
2. Load .env.local
3. Check USE_KEYCHAIN_FOR_DOTX
4. If enabled, read DOTENV_PRIVATE_KEY_LOCAL_SECRETS from Keychain
5. Load .env.local.secrets

Here is the core idea in TypeScript:

Open as GitHub Gist

import { execFileSync } from "node:child_process";
import { existsSync } from "node:fs";
import { resolve } from "node:path";
import { config } from "@dotenvx/dotenvx";

export function loadEnv(): void {
  for (const file of [".env", ".env.local"]) {
    const path = resolve(process.cwd(), file);
    if (existsSync(path)) {
      config({ path });
    }
  }

  const localSecretsPath = resolve(process.cwd(), ".env.local.secrets");
  if (!existsSync(localSecretsPath)) {
    return;
  }

  if (process.env.USE_KEYCHAIN_FOR_DOTX === "true") {
    try {
      process.env.DOTENV_PRIVATE_KEY_LOCAL_SECRETS = execFileSync(
        "security",
        [
          "find-generic-password",
          "-a",
          "LOCAL_SECRETS_DOTENVX_KEY",
          "-s",
          "LOCAL_SECRETS_DOTENVX_KEY",
          "-w",
        ],
        { encoding: "utf-8" },
      ).trim();
    } catch (err) {
      throw new Error(
        "Failed to read decryption key from macOS Keychain. " +
          "Make sure the LOCAL_SECRETS_DOTENVX_KEY item exists. " +
          "See scripts/store-keychain-key.sh for setup.",
        { cause: err },
      );
    }
  }

  config({ path: localSecretsPath, overload: true });

  // The private key has done its job. Remove it from the environment so it
  // is not visible in process.env dumps or child process inheritance.
  delete process.env.DOTENV_PRIVATE_KEY_LOCAL_SECRETS;
}

Three notes:

• execFileSync will throw on a non-zero exit, so the try/catch above turns a cryptic child-process error into a clear setup instruction
• the delete at the end matters: once dotenvx has decrypted the secrets into their individual env vars, the private key has no further purpose; leaving it in process.env means any code that inspects the environment (logging, diagnostics, error reporters) could leak the one key that decrypts the file
• do not log even partial key material during startup. That is easy to get wrong when debugging the integration

One thing this does not protect against: once your app is running, the decrypted secrets are plain strings in process.env. Anyone who can attach a Node debugger to your process can inspect memory directly.

Cross-process env snooping is more nuanced. On macOS 11+, SIP prevents processes from reading other processes’ environment variables, so this vector is largely closed on a default macOS install. On Linux, /proc/<pid>/environ is still readable by any process running as the same user. Either way, this pattern is about secrets at rest on disk, not secrets in a running process.

Next.js integration

If you are using Next.js, you cannot just call loadEnv() from anywhere and expect it to work. Next.js has its own env loading built in, and by the time your application code runs, it has already resolved which variables are available.

The right place to hook this in is instrumentation.ts (or .js). Next.js calls the register function exported from this file once when the server starts, before any routes or middleware run. That makes it the earliest reliable point to pull secrets from Keychain and inject them into process.env.

// instrumentation.ts
export async function register() {
  const { loadEnv } = await import("./lib/load-env");
  loadEnv();
}

The dynamic import is intentional. It keeps the Keychain and dotenvx logic out of the client bundle and avoids top-level side effects that could run at the wrong time.

Make sure instrumentation.ts is at your project root (next to next.config), and that you are on Next.js 15+ where the instrumentation hook is stable. On older versions (13.2 through 14.x) it works but requires setting experimental.instrumentationHook: true in your Next config.

Helper scripts for temporary decrypt/re-encrypt

I also like keeping two tiny helper scripts around so I can temporarily decrypt the file, edit it, and then re-encrypt it.

#!/usr/bin/env bash
# scripts/decrypt-local-secrets.sh
set -euo pipefail

KEYCHAIN_ITEM_NAME="LOCAL_SECRETS_DOTENVX_KEY"

export DOTENV_PRIVATE_KEY_LOCAL_SECRETS="$(
  security find-generic-password \
    -a "$KEYCHAIN_ITEM_NAME" \
    -s "$KEYCHAIN_ITEM_NAME" \
    -w
)"

pnpm exec dotenvx decrypt -f .env.local.secrets

#!/usr/bin/env bash
# scripts/encrypt-local-secrets.sh
set -euo pipefail

KEYCHAIN_ITEM_NAME="LOCAL_SECRETS_DOTENVX_KEY"

export DOTENV_PRIVATE_KEY_LOCAL_SECRETS="$(
  security find-generic-password \
    -a "$KEYCHAIN_ITEM_NAME" \
    -s "$KEYCHAIN_ITEM_NAME" \
    -w
)"

pnpm exec dotenvx encrypt -f .env.local.secrets

That gives you a simple workflow:

bash scripts/decrypt-local-secrets.sh
# edit .env.local.secrets
bash scripts/encrypt-local-secrets.sh

One risk here: if you decrypt the file, edit it, and forget to re-encrypt, your secrets are back to sitting in plaintext. A git pre-commit hook can catch this. Something like:

#!/usr/bin/env bash
# .husky/pre-commit or .git/hooks/pre-commit
if head -c 50 .env.local.secrets 2>/dev/null | grep -qv "^#/"; then
  echo "ERROR: .env.local.secrets appears to be decrypted. Run:"
  echo "  bash scripts/encrypt-local-secrets.sh"
  exit 1
fi

(dotenvx-encrypted files start with a comment header like #/-------------------[DOTENV]--------------------/, so checking for the absence of that prefix is a reasonable heuristic.)

Where this helps, and where it doesn’t

This pattern helps with:

• raising the cost of supply chain attacks that look for .env files
• repo-wide local file scraping
• accidental plaintext secret exposure in local tooling
• reducing how many places secrets live on disk
• avoiding accidental exposure during screen sharing and pair programming

It does not solve:

• malicious code running inside your process
• a debugger attached to your Node process (secrets are in memory as plain strings)
• cross-process env snooping on Linux (/proc/<pid>/environ); macOS SIP blocks this since Big Sur, but Linux does not
• secrets already exported into your shell
• logs or copy/paste leaks
• production secret management

Think of it as one useful layer, not as a silver bullet.

A note on screen sharing

If your secrets live in a plain-text .env.local, it is very easy to accidentally flash them on screen during a Zoom call, a pair programming session, or a live demo. All it takes is opening the wrong file, running cat on it, or having your editor preview it in a sidebar.

With encrypted .env.local.secrets, that file is just opaque ciphertext. Even if you open it on camera, nobody sees your database credentials or API keys. The decryption only happens at runtime, in memory, when your app starts, not when a human or a screen recording is looking at your filesystem.

This is not a reason to adopt the pattern on its own, but it is a nice side effect that has already saved me at least once.

The developer-experience bar matters

The reason I like this approach is that it is security work people may actually keep using.

Once set up, the workflow is close to normal local development:

• keep config in .env.local
• keep secrets in .env.local.secrets
• let the app pull the key from Keychain when needed

That is much more likely to stick than a system that feels “more secure” on paper but creates enough friction that everyone bypasses it.

If you want to adopt this

My suggestions:

1. Start with local-only encryption, not a big secret-sharing redesign.
2. Separate non-secret config from secrets first.
3. Make the Keychain path opt-in with a clear env flag.
4. Ensure .env.local loads before you evaluate that flag.
5. Audit helper scripts too, not just the main app boot path.
6. Back up your decryption key in a password manager before deleting .env.keys.
7. Add a pre-commit hook to catch unencrypted secrets files.
8. Never print keys, even partially, while debugging the integration.

That last point deserves repeating.

Security improvements have a way of being partially undone by “temporary” debugging statements.

Related tools worth looking at

If this pattern feels too lightweight for your needs, or you want something more structured, there are good adjacent tools in this space.

SOPS is a strong option when you want encrypted files as a first-class workflow, especially in teams already comfortable with cloud KMS, age, or GitOps-style config management.

DMNO goes in a different direction: schema-aware config, tooling around developer experience, and integrations with external secret stores. Their 1Password plugin is a good example if you want local development ergonomics tied more directly to a secrets manager instead of local encrypted .env files.

I do not see these as mutually exclusive with the smaller pattern in this post. They just sit at different points on the complexity and capability curve.

Closing thought

I do not think local .env files are going away anytime soon.

But I do think the threat model around them has changed.

A small amount of structure, encryption at rest, and OS-managed key storage can go a surprisingly long way without making local development miserable.

Followup: I also wrote a companion script that scans your machine for plaintext secrets sitting in .env files. It pairs well with this post as a way to find what needs encrypting. Find Plaintext Secrets Hiding in Your .env Files

It catches .env* key drift in pull requests and leaves a review comment with concrete fixes.

It uses Warp’s Oz under the hood to do the review, and it works great.

Why

Teams with multiple env files (.env, .env.production, .env.staging, etc) slowly drift.

Someone adds TWILIO_API_KEY to one file and forgets the others. CI passes, deploy goes out, and then something breaks in preview or prod.

Wizard of Drift catches that in the PR before merge.

The Real Problem

Most env drift bugs are boring and expensive:

• local works, preview fails
• preview works, production fails
• one service has a key, another service does not

And they are hard to catch in code review because reviewers are focused on app code, not checking every .env* file by hand.

Even worse, the PR diff can hide this. If a new key is added in .env.production only, nobody notices until a runtime path hits missing config.

This is the kind of failure that burns hours for no good reason.

What It Checks

• Scans .env* files in the repo
• Excludes .env.keys (never commit that)
• Compares key names only (not values)
• Handles DOTENV_PUBLIC_KEY naming rules per file:
  • .env expects DOTENV_PUBLIC_KEY
  • .env.<target> expects DOTENV_PUBLIC_KEY_<TARGET_UPPERCASE>
• Posts a PR review summary with missing key lines to add

Add It In 30 Seconds

name: Env Drift Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  env-drift:
    runs-on: ubuntu-latest
    steps:
      - uses: dotenvx/wizard-of-drift@v1
        with:
          warp_api_key: $
          github_token: $
          warp_agent_profile: "" # optional

Why A Coding Agent Works Well Here

This is a great use case for an agent because the input is high-context but bounded:

• list of env files
• extracted key sets
• the .env* diff in the PR
• explicit rules about DOTENV_PUBLIC_KEY naming

Wizard of Drift builds that context first, then gives the agent (in this case Oz) a tight prompt and asks for one output: a concise review summary with exact keys to add.

That pattern matters.

The agent is not guessing from vague code context. It is reviewing a purpose-built context document generated by CI, then returning actionable output directly into the PR conversation.

So the reviewer sees concrete fixes, not generic AI advice.

The Bigger Idea

This is the kind of workflow I want more of:

• static CI context
• AI agent review
• deterministic output in PR comments

And Oz was a great choice here because I wanted to easily trigger a coding agent from a GitHub action. Plus it supports any model and can be monitored from its dashboard.

The combination makes my .env workflows safer and easier to operate at scale. Dotenvx gives you the secure env model and the agent gives you a practical enforcement loop at review time.

Together, they remove a class of annoying config breakages before they merge.

If your team is still sharing .env values over Slack, this guide is for you. dotenvx encrypts your .env files so you can commit them directly to git. Secrets travel with your code, versioned and reviewable, but unreadable without the private key.

The tool itself is great. Getting it running on Vercel serverless is not as straightforward as the docs suggest. This tutorial walks through the full setup, including the runtime gotcha that is not well-documented and will cost you time if you hit it unprepared.

By the end you will have: encrypted .env files committed to git, automatic decryption in both local dev and Vercel deployments, and separate keys for preview vs production environments.

Why dotenvx

dotenvx is free, open source, and built by the creator of the original dotenv library. It replaces dotenv-vault (deprecated May 2024) with a simpler approach: instead of syncing secrets to a hosted service, it encrypts them in place using ECIES. The encrypted files live in your repo. You manage one private key per environment.

The benefits over the Slack-and-gitignore workflow:

• Version-controlled secrets. Changing a database URL shows up in your git diff. Rollbacks roll back secrets too.
• Instant onboarding. New teammates clone the repo and get all encrypted env files. Hand them the dev key and they are running.
• Multi-environment by default. Separate .env, .env.production, and .env.staging files, each with their own key pair.

Within a year of release, dotenvx crossed a million weekly npm installs, adopted by PayPal, NASA, Supabase, and AWS. It works. The setup on Vercel just needs a few extra steps.

Step 1: Install dotenvx

Install it as a dependency, not a devDependency. This is important because it needs to be available at runtime in Vercel’s serverless bundle.

npm install @dotenvx/dotenvx

Step 2: Encrypt Your .env Files

Run dotenvx encrypt in your project root. This encrypts each value in your .env file individually and generates a key pair. The public key gets added as DOTENV_PUBLIC_KEY inside the .env file. The private key goes into a new file called .env.keys — hold onto this, you will need these keys in Step 5.

dotenvx encrypt

For a production env file:

dotenvx encrypt -f .env.production

Add .env.keys to your .gitignore. The encrypted .env and .env.production files should be committed — that is the whole point. But .env.keys holds the private decryption keys and must stay local.

Step 3: Update Your Scripts

Wrap your dev and build commands with the dotenvx CLI so it decrypts before Next.js runs:

{
  "scripts": {
    "dev": "dotenvx run -- next dev",
    "build": "dotenvx run -- next build"
  }
}

At this point, local dev and builds work. Client-side NEXT_PUBLIC_* variables get inlined at build time. If that is all you need, you could stop here.

But if you have server-side variables like DATABASE_URL, keep going. This is where it gets tricky.

Step 4: Add the Instrumentation File

Here is the problem: Vercel serverless functions do not use next start. They invoke your route handlers directly, so the dotenvx run CLI wrapper is not present at runtime. Server-side process.env reads get nothing, and you get errors at runtime due to secrets not being available. The same issue applies to any serverless deployment target — Cloudflare Workers, AWS Lambda, etc. — anywhere the CLI wrapper is not invoked at runtime.

The fix is a Next.js instrumentation file. Since the encrypted .env files are committed to git, they are part of the deployment. You just need to decrypt them when the serverless function starts:

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { config } = await import('@dotenvx/dotenvx');

    const vercelEnv = process.env.VERCEL_ENV;

    if (vercelEnv === 'production') {
      config({ path: ['.env.production', '.env'], overload: true });
    } else {
      config({ path: ['.env'], overload: true });
    }
  }
}

Notice this uses VERCEL_ENV, not NODE_ENV. next build always sets NODE_ENV=production even for preview deploys. VERCEL_ENV correctly distinguishes production, preview, and development.

Step 5: Add Private Keys to Vercel

This is the step that connects everything. The instrumentation file from Step 4 calls dotenvx.config() to decrypt your .env files at runtime. But it needs the private keys to do that. Since the keys are not in git (they are in .env.keys which is gitignored), you need to add them to Vercel’s environment variables manually.

Open your local .env.keys file and copy the values. Then in your Vercel project dashboard, go to Settings > Environment Variables and add:

• DOTENV_PRIVATE_KEY — the key that decrypts .env. Scope it to Preview and Development.
• DOTENV_PRIVATE_KEY_PRODUCTION — the key that decrypts .env.production. Scope it to Production.

Or if you prefer the CLI, you can set them with the Vercel CLI directly:

# Preview and Development
vercel env add DOTENV_PRIVATE_KEY preview development

# Production
vercel env add DOTENV_PRIVATE_KEY_PRODUCTION production

Without these, the instrumentation file will silently fail to decrypt and your server-side process.env reads will be empty.

Step 6: Deploy and Verify

Commit your encrypted .env files and push. In the Vercel build logs, you should see dotenvx injecting from your env files. Test a server-side route that reads process.env to confirm runtime decryption is working.

If you see ECONNREFUSED errors, double check: is @dotenvx/dotenvx in dependencies (not devDependencies)? Is instrumentation.ts at the root of your app? Are the private keys set in Vercel’s dashboard?

The Day-to-Day Workflow

After setup, managing secrets is just:

# Add or update a dev secret
dotenvx set KEY value

# Add or update a production secret
dotenvx set KEY value -f .env.production

# Commit and push — picked up automatically on next deploy
git add .env .env.production && git commit -m "update secrets"

No dashboard. No Slack. No sync step.

Let AI Set It Up

Copy this prompt into your AI coding assistant to have it do the setup for you:

Set up dotenvx for encrypted environment variables in my Next.js project deployed on Vercel. Follow these steps exactly.

1. Install — Install @dotenvx/dotenvx as a DEPENDENCY (not devDependency). It must be in the production bundle because Vercel serverless functions need it at runtime.

2. Encrypt .env files — Run dotenvx encrypt to encrypt the .env file in place. For a separate production env file, also run dotenvx encrypt -f .env.production.

3. Update .gitignore — Add .env.keys to .gitignore. The encrypted .env and .env.production files SHOULD be committed to git. The .env.keys file with private keys should NOT be committed.

4. Update package.json scripts — Wrap dev and build commands with dotenvx run --.

5. Create instrumentation.ts — This is the critical step. Vercel serverless functions do NOT use next start. Without this file, server-side process.env reads will be empty. Use VERCEL_ENV (not NODE_ENV) to distinguish environments.

6. Configure Vercel environment variables — Add DOTENV_PRIVATE_KEY (Preview/Development) and DOTENV_PRIVATE_KEY_PRODUCTION (Production) from your .env.keys file.

7. Deploy and verify.

Reference: https://tonyvantur.com/writing/dotenvx-vercel

Resources

• dotenvx Vercel Platform Guide — Official docs for using dotenvx with Vercel
• dotenvx Documentation — Full reference for the dotenvx CLI and API
• dotenvx on GitHub — Source code and issue tracker
• Next.js Instrumentation — How the register() hook works

This was a real problem for us. We publish 64 npm packages, and rotating tokens across all of them by hand was not going to be sustainable. Every expiration meant touching dozens of pipelines and praying the next publish didn’t fail.

So we built a solution. Introducing Dotenvx Rotate - part of Dotenvx Ops.

How It Works

Install dotenvx-ops.

$ curl -sfS https://dotenvx.com/ops | sh

Run rotate npm connect to connect npm.

$ dotenvx-ops rotate npm connect

When prompted enter your npm username and password.

$ dotenvx-ops rotate npm connect
✔ npm username: USERNAME
✔ npm password: PASSWORD

This opens a local browser session, connecting your npm account.

IMPORTANT: Note that this is local only - this way we can bypass the need for storing your credentials.

Complete any 2FA steps manually.

On success, return to your CLI, and you will see a passcard created.

$ dotenvx-ops rotate npm connect
✔ npm username: USERNAME
✔ npm password: PASSWORD
✔ connected [https://ops.dotenvx.com/go/pas_1234..]

Dotenvx Passcards are special connectors allowing account access.

Next, use the passcard to rotate your npm token.

Rotate

Run rotate on the passcard.

$ dotenvx-ops rotate dotenvx://pas_1234..
⠏ rotating..

It takes 10-30 seconds. On success, it returns a Dotenvx Rotation Token (ROT).

$ dotenvx-ops rotate dotenvx://pas_1234..
✔ rotated [https://ops.dotenvx.com/go/pas_1234..]
⮕ next run [dotenvx-ops get dotenvx://rot_a2c4..]

Dotenvx Rotation Tokens (ROTs) are special tokens that can change value. You can think of them as proxy tokens.

Next, let’s get the value for it.

Get

Run get on the rotation token.

$ dotenvx-ops get dotenvx://rot_a2c4..
npm_d2cJ..

It returns your npm token. Cool!

Rotate Again

Run rotate on the passcard again.

$ dotenvx-ops rotate dotenvx://pas_1234..
✔ rotated [https://ops.dotenvx.com/go/pas_1234..]
⮕ next run [dotenvx-ops get dotenvx://rot_a2c4..]

And get the ROT again.

$ dotenvx-ops get dotenvx://rot_a2c4..
npm_cbGY..

The value changed. Way cool!

That’s the ROT at work. ROTs introduce a new key rotation primitive: the npm token rotates, the reference does not. This is useful for operations, especially CI/CD.

CI/CD

Previously, our CI/CD had npm publish with a hardcoded secrets.NPM_TOKEN:

npm:
  ...
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: '18.x'
        registry-url: 'https://registry.npmjs.org'
    - run: npm publish
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Step 1

We first replaced secrets.NPM_TOKEN with env.NODE_AUTH_TOKEN.

npm:
  ...
  runs-on: ubuntu-latest
  steps:
    ...
    - run: npm publish
      env:
        NODE_AUTH_TOKEN: ${{ env.NODE_AUTH_TOKEN }}

Step 2

Then we added a step to:

• Install dotenvx-ops
• Run dotenvx-ops get to echo its value to NODE_AUTH_TOKEN

npm:
  ...
  runs-on: ubuntu-latest
  steps:
    ...
    - run: |
        curl -sfS https://dotenvx.sh/ops | sh
        echo "NODE_AUTH_TOKEN=$(dotenvx-ops get dotenvx://rot_a2c4 --token '${{ secrets.DOTENVX_OPS_TOKEN }}')" >> $GITHUB_ENV
    - run: npm publish
      env:
        NODE_AUTH_TOKEN: ${{ env.NODE_AUTH_TOKEN }}

Step 3

Last, we set DOTENVX_OPS_TOKEN in GitHub Actions Secrets (or GitLab CI, CircleCI, or wherever you run your automated npm publishing).

Tip: Find your DOTENVX_OPS_TOKEN on your Dotenvx Settings Page.

On your next CI run, it will inject the latest rotated NPM token and successfully publish your npm module(s).

Incredible!

Conclusion

Publishing now works indefinitely with rotating NPM tokens, powered by a new rotation primitive (ROTs) and passcard connectors.

• NPM token leaked? Just rotate it - all your operations still work.
• Employee left who knew the old token? Rotate it - all your operations still work.
• NPM token should be rotated every N days for compliance? Put it on a schedule - all your operations still work.

This has worked really well for us. If it sounds useful, you can use it too. Sign up for Dotenvx Ops.

P.S. If you’re running this at enterprise scale with compliance requirements, scheduled rotation, or broader CI/CD concerns, please get in touch. We’d like to help.

¹ Strengthening npm security: Important changes to authentication and token management

In practice, Docker Compose secrets are just plaintext files in disguise, which introduces its own risks. Meanwhile, dotenvx takes a different approach with just-in-time secret injection that avoids leaving sensitive data lying around.

Good Idea, Unencrypted Reality

Docker Compose added a feature called secrets to keep passwords and API keys out of your Dockerfiles and environment variables. The idea sounds good. But here’s the catch: those secrets are just plaintext files.

Compose bind-mounts a plaintext file into your container under /run/secrets ¹. No encryption.

As a result, in a running container, an attacker (or malicious process) can simply read the unencrypted file from /run/secrets and obtain your secret – these secret files are mounted world-readable (mode 0444) ¹.

Plaintext Secrets at Rest

Why is a plaintext file at rest such a big deal? Because anything stored on disk is one stray commit or backup away from exposure. If you check that secret file into source control by mistake, or if your server gets compromised, the secret is sitting there in plain text.

Docker Compose avoids putting secrets in images or environment variables, but leaving them on the filesystem means they persist longer than they might need to. Long-lived plaintext secrets are an inviting target.

For example, a common slip-up is a developer accidentally committing a .env or secret file to GitHub – now your passwords are public. Even on a server, a misconfigured web route could unintentionally serve that file, or an attacker could find it among backups.

A secret that lives as plaintext on disk is always at risk of being read by someone unauthorized.

Environment Variables

On the other hand, environment variables vanish once the process stops and aren’t directly saved to disk. But environment variables have their own pitfalls if misused. If you print them in logs or leave them in an .env file on disk, you’re back to square one.

The takeaway here is that how you handle the secret matters more than the mechanism. Simply moving a secret from an env var to a file doesn’t automatically make it safe.

Dotenvx: Just-in-Time Secrets Injection

Dotenvx approaches secret management with a focus on minimal exposure. It injects your secrets at runtime only, via the command dotenvx run. How does this help?

First, it means you don’t leave secret values sitting around in a container’s environment or filesystem for longer than necessary. The dotenvx CLI loads the secrets from an encrypted .env file and injects them as environment variables only while launching your app, then your app uses them in-memory.

There’s no separate plaintext secret file hanging around permanently. In CI/CD, for example, dotenvx will decrypt your secrets and inject them “just in time” as the build or app starts.

Dotenvx: Encryption

Crucially, dotenvx lets you encrypt your .env files. With one command dotenvx encrypt, you transform your .env into an encrypted format.

Even if someone finds that file, they can’t read the secrets without the decryption key. It uses AES-256 encryption with ephemeral keys so that even if the encrypted .env file is exposed, its contents remain secure. ³ You can commit the encrypted .env to your repo safely – it’s just gibberish to anyone without the key.

Come runtime, you provide the key (often via an environment variable or a secret manager) and dotenvx seamlessly decrypts and injects the real values into your app. The end result: no plaintext secrets sitting at rest on your disk or in your container. They exist only in memory when needed.

How It Works

You run your app like this:

$ dotenvx run -- node app.js

Secrets are decrypted and loaded as environment variables just for that process. Nothing written to disk. No lingering files in containers.

Want to commit secrets to your repo? Encrypt them first:

$ dotenvx encrypt

Then you can safely version your encrypted .env file. It’s useless without the decryption key.

It’s that easy and no plaintext files sitting around! Great!

Comparison

Takeaway

Docker Compose secrets look safer than env vars — but they aren’t encrypted, and they persist longer. Meanwhile, dotenvx focuses on short-lived, encrypted, just-in-time secrets.

If you care about reducing blast radius and limiting exposure, dotenvx is a solid and modern option to consider.

To learn more, read the whitepaper.

¹ docker.com ² news.ycombinator.com ³ github.com/dotenvx/dotenvx

Dotenvx works with Claude MCP. Here’s how to get it in your Claude.

Step 1

Type claude mcp add.

$ claude mcp add
Add MCP Server

Choose a unique name for this server:

> dotenvx

Step 2

For Server Scope, choose User.

Server Scope

Choose where this server will be available:

  
  Project (shared via .mcp.json)
  Local (private to you in this project)
> User (available in all your projects)

Step 3

For Transport Type, choose Stdio.

Transport Type

Choose how Claude Code will connect to your MCP server:

> Stdio (command-line process)
  SSE (Server-Sent Events over HTTP)

Step 4

Enter npx @dotenvx/dotenvx as the server command.

Server Command

Enter the full command to start your MCP server.

> npx @dotenvx/dotenvx

Confirm that. That’s it!

Now you can ask Claude to encrypt my .env file and it will do it!

Hey Claude, encrypt my .env file please.

Bonus

Additionally, be sure to share llms.txt and llms-full.txt with Claude to make it smarter about all this.

Thanks for using Dotenvx.

If you enjoyed this post, please share dotenvx with friends or star it on GitHub to help spread the word.

That growth didn’t happen by accident—dotenvx development has been heavy with 88 releases in 8 months. That’s a new release every 2.75 days!

Today, it is a world-class tool–handling .env parsing, variable expansion, command substitution, encrypted .env files, and more better than anything else can. Each day, hundreds of software engineers newly learn of, and begin using, dotenvx.

As a result, it’s starting to grow into something bigger—a community, an ecosystem, and a standard.

Community

Dotenvx has grown fast, and a big part of that is developer involvement. In just eight months, engineers have contributed ideas, issues, and pull requests that shaped its direction.

• GitHub Activity. More than 250 issues filed, 275 PRs created, and 60,000 lines of code written in the last eight months.
• Third-Party Documentation. Users wrote about dotenvx, made videos about dotenvx, recommended dotenvx, and much more.
• Adoption and Dependents. Most significantly, major projects adopted dotenvx and became dotenvx dependents.
  • NASA
  • AWS
  • Supabase
  • Cloudflare

This kind of community involvement makes dotenvx better. The feedback loop between users and development is tight, and that’s been key to its fast growth.

Ecosystem

Dotenvx isn’t just a CLI—it’s extending into the tools developers use every day.

• VS Code Extension. Decrypt your encrypted .env files in VS Code with the Dotenvx VS Code Extension.
• Chrome Extension. Decrypt your encrypted .env files directly on GitHub with the Dotenvx Chrome Extension.
• Buildpacks. Install dotenvx to Heroku (or any platform that supports buildpacks) with the Dotenvx Buildpack.

This growing ecosystem ensures that no matter where developers work—local editors, browsers, or cloud platforms—dotenvx is increasingly there to seamlessly handle secrets.

Standard

Dotenvx isn’t just widely used—it’s built on a foundation that makes it the right way to handle secrets.

From the whitepaper:

Dotenvx: Reducing Secrets Risk with Cryptographic Separation

Abstract. An ideal secrets solution would not only centralize secrets but also contain the fallout of a breach. While secrets managers offer centralized storage and distribution, their design creates a large blast radius, risking exposure of thousands or even millions of secrets. We propose a solution that reduces the blast radius by splitting secrets management into two distinct components: an encrypted secrets file and a separate decryption key.

This approach—cryptographic separation—ensures that even if one component is compromised, the overall security of secrets remains intact. The whitepaper breaks down the problem and solution, and “it makes a great case for dotenvx.” ¹

By stating the problem well and implementing good DX, dotenvx is emerging as a new standard for secrets management of .env files. It’s pretty incredible.

Conclusion

What started as a rethink of .env files has quickly turned into something much bigger. In just eight months, dotenvx has gone from an emerging idea to an essential tool, trusted by developers and major platforms alike.

With over 1 million monthly installs, an active and engaged community, an expanding ecosystem, and a well-defined standard, dotenvx isn’t just growing—it’s reshaping how secrets are managed in modern development.

And this is only the beginning. 💪

If you enjoyed this post, please share dotenvx with friends or star it on GitHub to help spread the word.

Last year around this time, I launched the first few versions of dotenvx.

I remember we said goodbye to family - after a wonderful Thanksgiving meal - and headed on a road trip to Arizona to visit my longtime friend, Will VanOosting.

We’ve been friends since kids - playing pony league baseball. As teenagers we used to go to the Temecula mall, get girls’ numbers, and then invite them to the pool hall later. Will cleaned up. He was a real lady’s man!

As we grew older, he pursued a life of adventure, trucking across the country, and I pursued a creative life, making software at startups. We always stayed in touch.

Anyway, we left Thanksgiving and headed toward Kingman, Arizona. But before visiting Will and his family, we headed further to catch an old train for the Grand Canyon.

I remember it was cold, and we got ‘robbed’ on the train by cowboys on horses. It was a real adventure for the kids. For their souvenirs they each chose a stuffed animal. Those two little stuffed animals have become like part of the family - joining us on so many trips. ‘Bambi’ the deer - Sophia’s choice. And ‘Frost’ the wolf - Charlie’s.

We returned from the Grand Canyon and spent the next day hanging out with Will’s family. It was great to catch up. His parents were also in town, and I hadn’t seen them in probably a decade. Somehow we all ended up at a pool hall at the end of the day.

Good memories, that trip.

What I don’t remember is late nights and early mornings writing code. Yet, dotenvx’s git history says I did.

That was over 130,000 lines of code ago.

Over 130,000 lines of code.

Incredible.

Probably that part was hard. Because as you know it’s tough carving out an hour here, 30 minutes there, to pursue a dream.

But it adds up.

And as I reflect back on the last year, I am thankful for that hard work and enormously thankful for the many people who chose to take a chance on dotenvx, and now, use it daily. Thank you so much. 🙏

But most of all, I’m thankful for family, friends, and the memories we’ve had together. They are cherished like gold.

Happy Thanksgiving all! 🦃

In response to that, we’re one of the first software projects worldwide to offer that ability to devs. If you’re using dotenvx we’ve created the following files for your llm consumption:

• llms.txt
• llms-full.txt.

They are plain text files:

# dotenvx

> Secrets for agents

## Docs

- [Advanced](https://dotenvx.com/docs/advanced.html): Advanced usage and commands for `dotenvx`
- [dotenvx ext genexample directory](https://dotenvx.com/docs/advanced/genexample-directory.html): Generate a .env.example file inside the specified directory. Useful for monorepos.
- [dotenvx ext genexample -f](https://dotenvx.com/docs/advanced/genexample-f.html): Pass multiple .env files to generate your .env.example file from the combination of their contents.
- [dotenvx ext genexample](https://dotenvx.com/docs/advanced/genexample.html): Generate a .env.example file from your current .env file contents.
- [dotenvx get --all --pretty-print](https://dotenvx.com/docs/advanced/get-all-pretty-print.html): Make the output more readable - pretty print it.
- [dotenvx get --all](https://dotenvx.com/docs/advanced/get-all.html): Return preset machine envs as well.
- [dotenvx get --format eval](https://dotenvx.com/docs/advanced/get-eval.html): Return an eval-ready shell formatted response of all key/value pairs in a .env file.
- [dotenvx get](https://dotenvx.com/docs/advanced/get-json.html): Return a json response of all key/value pairs in a .env file.
- [dotenvx get KEY --convention=nextjs](https://dotenvx.com/docs/advanced/get-key-convention.html): Return a single environment variable's value using the Next.js convention
- [dotenvx get KEY --env](https://dotenvx.com/docs/advanced/get-key-env.html): Return a single environment variable's value from a --env string.
- [dotenvx get KEY -f](https://dotenvx.com/docs/advanced/get-key-f.html): Return a single environment variable's value from a specific .env file.
- [dotenvx get KEY --overload](https://dotenvx.com/docs/advanced/get-key-overload.html): Return a single environment variable's value where each found value is overloaded.
- [dotenvx get KEY](https://dotenvx.com/docs/advanced/get-key.html): Return a single environment variable's value.
- [dotenvx get --format shell](https://dotenvx.com/docs/advanced/get-shell.html): Return a shell formatted response of all key/value pairs in a .env file.
- [dotenvx keypair -f](https://dotenvx.com/docs/advanced/keypair-f.html): Print public/private keys for chosen .env* files.
- [dotenvx keypair KEY](https://dotenvx.com/docs/advanced/keypair-key.html): Print specific keypair for .env file.
- [dotenvx keypair --format shell](https://dotenvx.com/docs/advanced/keypair-shell.html): Print a shell formatted response of public/private keys.
- [dotenvx keypair](https://dotenvx.com/docs/advanced/keypair.html): Print public/private keys for .env file.
- [dotenvx ls directory](https://dotenvx.com/docs/advanced/ls-directory.html): Print all .env files inside a specified path to a directory.
- [dotenvx ls -ef](https://dotenvx.com/docs/advanced/ls-ef.html): Glob .env filenames excluding a wildcard.
- [dotenvx ls -f](https://dotenvx.com/docs/advanced/ls-f.html): Glob .env filenames matching a wildcard.
- [dotenvx ls](https://dotenvx.com/docs/advanced/ls.html): Print all .env files in a tree structure.
- [dotenvx run - Command Substitution](https://dotenvx.com/docs/advanced/run-command-substitution.html): Add the output of a command to one of your variables in your .env file.
...

But they can greatly improve your Cursor, ChatGPT, and LLM experience.

You can instruct ChatGPT or Cursor as easily as this:

That’s it. We hope it helps improve your coding experience ever so slightly. May you learn kung fu!

P.S. If you want to generate your own llms.txt file we wrote npx llmstxt to easily generate an llms.txt file from your sitemap.xml.

It’s a far cry from dotenv’s 18.7 Million, but it’s growing fast - faster than dotenv initially grew. - Mot

Here’s some notable and interesting projects using dotenvx.

• vxrn ⚛️
• CocosEngine 🎮
• Stack’s sbtc 💰
• Facebook’s Rapid 👍
• French Government 🇫🇷

vxrn - 642 🌟

From the same guy - Nate Wienert - that brought you Tamagui, vxrn lets you build and serve your React Native apps using only Vite.

github.com/universal-future/vxrn

CocosEngine Docs - 297 🌟

Cocos game engine accounts for a substantial portion of the mobile gaming market in China - estimated around 40%. The platform has a community of over 1.7 million developers and uses dotenvx to help power its open source documentation.

github.com/cocos/cocos-docs

Stacks sbtc - 202 🌟

Stacks is the leading Bitcoin L2. They are using dotenvx in their repo containing sbtc.

github.com/stacks-network/sbtc

Facebook Rapid - 505 🌟

A Meta project, Rapid is an OpenStreetMap editing tool using AI.

github.com/facebook/Rapid

French Government 🇫🇷 - 26 🌟

MonComptePro is the French Republic’s new identify provider - providing identity and authorization as a service to French professionals, healthcare providers, and companies. It’s an open sourced service of the state.

github.com/numerique-gouv/moncomptepro

Incroyable! Merci aux développeurs d’utiliser dotenvx. 🍷🥐

What it takes 💪

It takes a lot.

• 110,000 lines of code written ¹
• 13,777 lines the final result ²
• 1,658 line README ³
• 188 versions ⁴
• 93 doc pages ⁵
• 1 website ⁶
• 10 months of labor ⁷

Plus, dotenvx has the advantage of association to dotenv - making it easier to get word out! Still it takes a great deal of effort to build a well-adopted developer tool.

I salute all other devs doing the same. We’re playing on hard mode. 🫡

¹ 110,000 lines of code:

² 13,777 lines the final result

³ 1,658 line README

⁴ 188 versions

⁵ 93 doc pages

⁶ 1 Website

⁷ 10 months of labor