# varlock varlock is an [[Open Source]] tool for managing environment variables, built by DMNO Inc. and released under the [[MIT License]]. Its tagline says the whole thing: *"AI-safe .env files: Schemas for agents, secrets for humans."* It's built on top of `@env-spec`, a specification for annotating `.env` files, and it is deliberately language and framework agnostic. The [[JavaScript]] integrations get the most attention, but the tool is meant for any project that needs configuration at build or boot time. ## The problem it goes after `.env` files have been the default for years, and they have always had the same three holes: - **`.env.example` drifts.** You add a variable, you forget the example file, a teammate clones the repo and spends an hour finding out why nothing boots. - **Misconfiguration shows up at runtime.** A missing or malformed variable becomes a crash in production instead of an error at startup. - **Secrets sit in plaintext exactly where tools look.** That was survivable when only you read your own files. It stopped being survivable once [[AI Agents]] started reading your project to understand it, and potentially sending what they read somewhere else. The third one is what makes varlock timely rather than just tidy. Your `.env` is now part of the context window. ## How it works One file, `.env.schema`, replaces `.env.example`. It declares what each variable is, using JSDoc-style decorators: ```bash # @type=enum(development, preview, production, test) APP_ENV=development # @type=port API_PORT=8080 # @required @sensitive @type=string(startsWith=sk-) OPENAI_API_KEY= ``` The decorators (`@type`, `@required`, `@sensitive`, `@defaultSensitive`) do several jobs at once: documentation, validation, [[TypeScript]] type generation with IDE completion, and the marking of which values must never be shown. Values can come from anywhere. Composed across defaults, per-environment overrides, git-ignored local files, and process variables, or pulled from an external secret manager through function calls like `op("op://api-prod/xyz/auth-token")`. Over a dozen backends are supported: 1Password, AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, Infisical, Bitwarden, Google Secret Manager. `.env.local` is encrypted device-locally with hardware backing, so nothing sits in plaintext. The CLI is small: - `varlock load` validates the schema and shows the resolved values - `varlock run -- <command>` injects them into a subprocess - `varlock scan` hunts for leaked secrets in your code, and runs as a git hook - `varlock proxy run` starts the local credential proxy It also works as a drop-in replacement for dotenv with `import 'varlock/auto-load'`, and integrates with [[Next.js]], Vite, Astro and SvelteKit. Install via `npx varlock init`, Homebrew, a curl script, or the Docker image. ## The agent-safety part Two mechanisms, and they're different from each other. **The schema is the agent's copy.** An agent reading `.env.schema` learns every variable name, its type, its validation rules and its description. Enough to generate correct code. It never sees a single value. Combine that with `varlock scan` and you also catch the secrets that agent-written code accidentally hardcodes. **The credential proxy handles the runtime case.** When an agent actually has to make an authenticated call, it receives a placeholder instead of the real credential, and the real value gets injected at a verified network boundary. The agent can use the key without ever holding it. [[Hermes Agent]] shipped the same mechanism for Docker sandboxes in the same month, independently. Two projects, different starting points, identical answer: stand-in inside, real value swapped at egress. That convergence is a good sign the pattern is right rather than clever. Alongside that, sensitive values are redacted from logs at runtime, which closes the oldest leak of all: the secret that ends up in a stack trace. ## References - [varlock.dev](https://varlock.dev/) - [varlock on GitHub](https://github.com/dmno-dev/varlock) - [Documentation](https://varlock.dev/getting-started/introduction/) - [Blog](https://varlock.dev/blog/) - [Community Discord](https://chat.dmno.dev/) ## Related - [[AI Agents]] - [[Hermes Agent]] — same credential-proxy pattern for Docker sandboxes - [[DrSkill]] — scans for secrets in committable agent config - [[Claude Code]] - [[TypeScript]] - [[JavaScript]] - [[Node.js]] - [[Next.js]] - [[Open Source]] - [[MIT License]] - [[DevOps]]