Varlock: schema-first env files that stay safe around AI tooling

Introduction

varlock.dev markets Varlock as “AI-safe .env files”: a workflow where .env.schema holds the authoritative list of variables, constraints, and documentation—but not the secrets themselves—while real values resolve at runtime via git-ignored files, plugins, or your shell environment. The project is MIT-licensed open source (dmno-dev/varlock on GitHub) alongside reference docs at varlock.dev.

If you already treat agent sessions as hostile to accidentally pasted keys (for example alongside a minimal harness like Pi), Varlock is pitched as infrastructure: schema for agents and CI, plaintext secrets only where you explicitly put them.

Cover art here is Varlock’s default Open Graph raster from the upstream site package (packages/varlock-website/public/default-og-image-new.png), same MIT-licensed monorepo as the tool.

Why .env.example drifts (and what Varlock proposes instead)

Teams often duplicate structure between .env, .env.example, README tables, and hand-written TypeScript process.env types. One change updates one file but not another; agents read oversized .env-like blobs and may echo secrets back into transcripts or commits.

Varlock’s answer is .env.schema as a single checked-in artifact annotated with @env-spec: comment-line decorators (similar in spirit to JSDoc) that encode types, optionality/sensitivity defaults, interpolation, docs links, plugins, and more. Human-written secrets belong in .env.local or other ignored layers; the README contrasts that explicitly with drifting .env.example files (Varlock README).

A minimal shape from upstream looks conceptually like this (structure and decorators are illustrative; paste from the README when bootstrapping a real repo):

Copy
# @defaultSensitive=false @defaultRequired=infer @currentEnv=$APP_ENV
# ---
# @type=enum(development, preview, production, test)
APP_ENV=development

# @type=port
API_PORT=8080

# @type=url
API_URL=http://localhost:${API_PORT}

# @required @sensitive @type=string(startsWith=sk-)
OPENAI_API_KEY=

The @plugin decorator loads optional npm packages—for example @varlock/1password-plugin—so secrets can resolve from op(…) references instead of pasted literals (README § plugins). Published first-party backends also include Infisical, AWS Secrets Manager, Azure Key Vault, Google Secret Manager, HashiCorp Vault, Bitwarden, KeePass, pass-family tools, Passbolt, and Proton Pass (see the README’s Published Packages tables).

Site copy also describes built-in encryption for local overrides in .env.local so overrides need not stay plaintext on disk—a separate concern from .env.schema, which intentionally stays readable.

@env-spec as the interchange format

Implementation-wise, @env-spec is documented as Varlock’s DSL: comments above keys carry schema metadata, and tooling parses them into structured config. Official entry points linked from the repository are the @env-spec overview and an RFC-style discussion on GitHub (discussion #17).

That separation matters architecturally: you can evolve editors, MCP servers, and generators around one grammar instead of scattering ad hoc validators.

CLI: resolve, guard, inject

Rough workflow straight from upstream:

• varlock load — validate .env.schema and show resolved variables (sanitized where sensitive).
• varlock run -- <cmd> — resolve and validate, then execute <cmd> with injected environment.
• varlock scan — scan your tree for leaked secrets (README pairs this with git hooks).

The Docker image ghcr.io/dmno-dev/varlock:latest is listed as an install path (README Installation); local setup also supports npx varlock init, Homebrew dmno-dev/tap/varlock, or the documented install shell script (https://varlock.dev/install.sh).

Marketing material calls out runtime protections: log/console redaction, leak detection hooks in bundled/browser contexts when those integrations apply, and clearer failure modes when validation trips—consult the integrations you actually enable rather than assuming every stack gets every guardrail automatically.

JavaScript and frameworks

For plain Node, the varlock/auto-load import path shells out via the CLI, hydrates process.env, wires Varlock runtime behavior (including ENV and optional protections per docs), and is documented as the primary integration—with an explicit caveat: varlock/auto-load targets Node.js 22+ as stated on that page.

Alternatively, varlock run -- node … avoids injecting runtime shim code; ENV from varlock/env is then unavailable, but process.env still receives validated values. Framework integrations published in the README include @varlock/nextjs-integration, @varlock/vite-integration, and @varlock/astro-integration (npm listings linked from README).

Editor and MCP ergonomics

The repository ships an official VS Code / Open VSX “env-spec language” extension (varlock.env-spec-language on Marketplace; link in README).

For MCP-capable assistants, Varlock publishes HTTP and SSE MCP servers that proxy documentation (for example https://docs.mcp.varlock.dev/mcp per the README), with wiring instructions under guides/mcp/—useful when you want citations to converge on canonical docs pages instead of guesswork.

When Varlock shines—and when not to pretend it solves everything

Good fits: Polyglot repos where varlock run can front Python/Go/Ruby scripts uniformly; JS monorepos where Astro/Next/Vite integrations mesh with your toolchain; organizations already standardizing on 1Password, cloud secret managers, or Infisical; teams whose biggest pain is .env/agent drift coupled with preventable leaks.

Caveats: You still need disciplined IAM, least privilege on backends and secret stores, CI rotation, and reviewer habits—schema tooling does not replace vault policy.

Conclusion

Varlock bundles a checked-in .env.schema, @env-spec decorators, the varlock load/run/scan CLI, plugin-backed secret backends, and first-class JavaScript tooling so collaborators and autonomous tools can share intent and validation rules without sharing plaintext secrets. Pair it with whichever agent workflow you already use—for example reviewing diffs closely in a harness like Pi—and treat varlock scan plus git hooks as a second line behind social process.

Facts and package names above follow dmno-dev/varlock’s README and varlock.dev integration pages as of mid‑May 2026; CLI flags and decorators evolve quickly, so keep the official reference open while you migrate from plain dotenv.