AI-safe .env files: Schemas for agents, Secrets for humans.
npm install varlock
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.
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
Framework Integrations
| Package | Published listing page |
|---|---|
| @varlock/astro-integration |  |
| @varlock/cloudflare-integration |  |
| @varlock/expo-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.