Reserved variables

varlock reserves a couple of environment variable namespaces for its own use. Knowing them helps you avoid surprises and understand how varlock passes state between processes.

Prefix	Example	Who sets it
VARLOCK_* (no underscore)	VARLOCK_ENV	varlock (computed); see Builtin variables
_VARLOCK_* (single underscore)	_VARLOCK_ENV_KEY	you, to configure varlock’s behavior
__VARLOCK_* (double underscore)	__VARLOCK_ENV	varlock internals, injected automatically; never set these yourself

The _VARLOCK_ prefix is reserved

Config items whose key starts with _VARLOCK_ are reserved for varlock. They are excluded from the injected env blob, generated types, and override provenance, even if you define one in your .env.schema. varlock emits a warning if you do, since such an item won’t behave like a normal config value. Don’t name your own variables with this prefix.

Configuration variables (_VARLOCK_*)

Set these in your shell, CI, or deploy environment to configure varlock’s behavior.

_VARLOCK_ENV_KEY

Encryption key used to decrypt the injected env blob at runtime. Typically set in deploy environments. See Encrypted deployments.

_VARLOCK_CACHE_KEY

Encryption key for the on-disk resolved-value cache. When set (e.g. as a CI secret), it enables the disk cache in environments without OS keychain access. See Caching.

_VARLOCK_REDACT_STDOUT

Overrides varlock run output redaction:

• true / 1: force redaction on (only applies to piped/redirected output; errors if attached to an interactive terminal)
• false / 0: disable redaction entirely

The --redact-stdout / --no-redact-stdout flags take precedence over this env var. Useful when you can’t easily change the command being run, for example in a wrapper script or CI config.

_VARLOCK_FILTER

Fallback for the --filter flag on varlock load / varlock run. An explicit --filter flag takes precedence over this env var. Useful when you can’t easily pass a CLI flag, for example a wrapper script, CI config, or a build-time integration that invokes varlock’s loading APIs directly.

_VARLOCK_FILTER="#billing" varlock load --format json

_VARLOCK_DYNAMIC_BUILD_ACCESS_MODE

Set to warn to downgrade the build/prerender-time guard on public+dynamic config access from an error to a one-time warning per key. Useful while migrating an existing app that still reads dynamic public values in prerendered pages.

_VARLOCK_THROW_ON_LOAD_ERROR

When set (1 / true), varlock/auto-load throws the error on a load failure instead of exiting, so an already-initialized error tracker (e.g. Sentry) can capture it via its uncaughtException handler. Setting a globalThis._varlockOnLoadError hook enables the same throw behavior. See Reporting load failures.

Internal variables (__VARLOCK_*)

These are injected automatically so that varlock state survives across process boundaries. You should never set them yourself. They’re documented here only so you recognize them if you see them in a process environment.

__VARLOCK_ENV

The serialized env graph (resolved config values plus metadata) injected by varlock run and build-time integrations, so the runtime can load your config without re-invoking the CLI. @internal items are excluded from this blob by default everywhere it’s built, including framework integrations.

__VARLOCK_RUN

A marker set so a child process can detect that it is running under varlock run.

__VARLOCK_EXECUTION_PHASE

Set to build by build-time integrations (e.g. the Vite plugin during vite build) so the runtime can detect app code executing during build/prerender and apply the public+dynamic access guard.