Varlock

<p align="center"> <a href="https://varlock.dev" target="_blank" rel="noopener noreferrer"> <img src="/packages/varlock-website/public/github-readme-banner.png" alt="Varlock banner"> </a> </p> <br/> <p align="center"> <a href="https://npmjs.com/package/varlock"><img src="https://img.shields.io/npm/v/varlock.svg" alt="npm package"></a> <a href="/LICENSE.md"><img src="https://img.shields.io/npm/l/varlock.svg" alt="license"></a> <a href="https://nodejs.org/en/about/previous-releases"><img src="https://img.shields.io/node/v/varlock.svg" alt="node compatibility"></a> <a href="https://github.com/dmno-dev/varlock/actions/workflows/test.yaml"><img src="https://img.shields.io/github/actions/workflow/status/dmno-dev/varlock/test.yaml?style=flat&logo=github&label=CI" alt="build status"></a> <a href="https://chat.dmno.dev"><img src="https://img.shields.io/badge/chat-discord-5865F2?style=flat&logo=discord" alt="discord chat"></a> </p> <br/>

Varlock

AI-safe .env files: Schemas for agents, Secrets for humans.

• 🤖 AI-safe config — agents read your schema, never your secrets
• 🔍 proactive leak scanning via varlock scan + git hooks
• 🔏 runtime protection — log redaction and leak prevention
• 🛡️ validation, coercion, type safety w/ IntelliSense
• 🌐 flexible multi-environment management — auto .env.* loading and explicit import
• 🔌 plugins to pull data from various backends (1Password, Infisical, AWS, Azure, GCP, HCP Vault, more!)

Unlike .env.example, your .env.schema is a single source of truth, built for collaboration, that will never be out of sync.

# @defaultSensitive=false @defaultRequired=infer @currentEnv=$APP_ENV
# ---
# our environment flag, will control automatic loading of `.env.xxx` files
# @type=enum(development, preview, production, test)
APP_ENV=development # default value, can override

# @type=port
API_PORT=8080 # non-sensitive values can be set directly

# API url including _expansion_ referencing another env var
# @type=url
API_URL=http://localhost:${API_PORT}

# sensitive api key, with extra validation
# @required @sensitive @type=string(startsWith=sk-)
OPENAI_API_KEY=

Flexible plugin system: adds new decorators, functions, types - enables secure declarative secret loading.

# @plugin(@varlock/1password-plugin)
# @initOp(token=$OP_TOKEN, allowAppAuth=forEnv(dev), account=acmeco)
# ---

# @type=opServiceAccountToken @sensitive
OP_TOKEN=

# Fetch secrets using 1Password secret references
DB_PASS=op(op://my-vault/database-password/password)
API_KEY=op(op://api-vault/stripe/api-key)

Installation

You can get started with varlock by installing the CLI:

# Run the installation wizard, which will install as a dependency in a JavaScript project
npx varlock init

# Or install as standalone binary
brew install dmno-dev/tap/varlock # via homebrew
curl -sSfL https://varlock.dev/install.sh | sh -s # via cURL

# Or use the official Docker image
docker pull ghcr.io/dmno-dev/varlock:latest

See the full installation docs or the Docker guide for more information.

Workflow

Validate your .env.schema and pretty print your environment variables with:

varlock load

If you need to pass resolved env vars into another process, you can run:

varlock run -- python script.py

In many cases you can use our drop-in integrations for seamless experience - with additional security guardrails, like log redaction and leak prevention.

AI-Safe Config

Your .env.schema gives AI agents full context on your config — variable names, types, validation rules, descriptions — without ever exposing secret values. Combined with varlock scan to catch leaked secrets in AI-generated code, varlock is purpose-built for the AI era. Learn more in the AI-safe config guide.

@env-spec

Varlock is built on top of @env-spec, a new DSL for attaching a schema and additional functionality to .env files using JSDoc style comments. The @env-spec package contains a parser and info about the spec itself.

• @env-spec docs
• @env-spec RFC

Published Packages

Core

| Package | Published listing page | | --- | --- | | varlock | | | @env-spec/parser | | | @env-spec VSCode extension | VSCode Marketplace, Open VSX Registry | | varlock Docker image | GitHub Container Registry |

Plugins

| Package | Published listing page | | --- | --- | | @varlock/1password-plugin | | | @varlock/aws-secrets-plugin | | | @varlock/azure-key-vault-plugin | | | @varlock/bitwarden-plugin | | | @varlock/google-secret-manager-plugin | | | @varlock/hashicorp-vault-plugin | | | @varlock/infisical-plugin | | | @varlock/pass-plugin | |

Framework Integrations

| Package | Published listing page | | --- | --- | | @varlock/astro-integration | | | @varlock/nextjs-integration | | | @varlock/vite-integration | |

MCP Servers

| MCP Server | Link | URL | | --- | --- | --- | | Varlock Docs (HTTP) | Installation | https://docs.mcp.varlock.dev/mcp | | Varlock Docs (SSE) | Installation | https://docs.mcp.varlock.dev/sse |

Examples

Examples of integrating varlock in various frameworks and situations can be found in the Varlock examples repo

Development & Contribution

See CONTRIBUTING.md for more information.