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

Plugins

Framework Integrations

MCP Servers

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.

Thanks to

CI infrastructure sponsored by Depot, fast GitHub Actions runners.