diff --git a/.env.example b/.env.example
deleted file mode 100644
index c5daeb201..000000000
--- a/.env.example
+++ /dev/null
@@ -1,29 +0,0 @@
-LITEFS_DIR="/litefs/data"
-DATABASE_PATH="./prisma/data.db"
-DATABASE_URL="file:./data.db?connection_limit=1"
-CACHE_DATABASE_PATH="./other/cache.db"
-SESSION_SECRET="super-duper-s3cret"
-HONEYPOT_SECRET="super-duper-s3cret"
-RESEND_API_KEY="re_blAh_blaHBlaHblahBLAhBlAh"
-SENTRY_DSN="your-dsn"
-
-# this is set to a random value in the Dockerfile
-INTERNAL_COMMAND_TOKEN="some-made-up-token"
-
-# the mocks and some code rely on these two being prefixed with "MOCK_"
-# if they aren't then the real github api will be attempted
-GITHUB_CLIENT_ID="MOCK_GITHUB_CLIENT_ID"
-GITHUB_CLIENT_SECRET="MOCK_GITHUB_CLIENT_SECRET"
-GITHUB_TOKEN="MOCK_GITHUB_TOKEN"
-GITHUB_REDIRECT_URI="https://example.com/auth/github/callback"
-
-# set this to false to prevent search engines from indexing the website
-# default to allow indexing for seo safety
-ALLOW_INDEXING="true"
-
-# Tigris Object Storage (S3-compatible) Configuration
-AWS_ACCESS_KEY_ID="mock-access-key"
-AWS_SECRET_ACCESS_KEY="mock-secret-key"
-AWS_REGION="auto"
-AWS_ENDPOINT_URL_S3="https://fly.storage.tigris.dev"
-BUCKET_NAME="mock-bucket"
diff --git a/.env.schema b/.env.schema
new file mode 100644
index 000000000..5f242dc3e
--- /dev/null
+++ b/.env.schema
@@ -0,0 +1,102 @@
+# This env file uses @env-spec - see https://varlock.dev/env-spec for more info
+# 
+# @defaultRequired=true @defaultSensitive=false
+# @currentEnv=$NODE_ENV
+# @generateTypes(lang=ts, path=types/env-vars.d.ts)
+# ----------
+
+# @type=enum(development, production, test)
+NODE_ENV=development
+# @type=enum(development, production, test)
+MODE=$NODE_ENV
+
+# @type=port
+PORT=3000
+
+LITEFS_DIR="/litefs/data"
+DATABASE_PATH="./prisma/data.db"
+DATABASE_URL="file:./data.db?connection_limit=1"
+CACHE_DATABASE_PATH="./other/cache.db"
+
+# used to secure sessions
+# @sensitive
+# @docs(https://stack-staging.epicweb.dev/topic/deployment)
+SESSION_SECRET="super-duper-s3cret"
+
+# encryption seed for honeypot server
+# @sensitive
+# @docs(https://stack-staging.epicweb.dev/topic/deployment)
+HONEYPOT_SECRET="super-duper-s3cret"
+
+# this is set to a random value in the Dockerfile
+# @sensitive
+INTERNAL_COMMAND_TOKEN="some-made-up-token"
+
+# set to false to prevent search engines from indexing the website (defaults to allow)
+ALLOW_INDEXING=true
+
+# enables mocks for external services
+MOCKS=forEnv(development, test)
+
+# will be set to curent commit sha in deployments
+# @optional
+COMMIT_SHA=
+
+# API key for Resend (email service)
+# @type=string(startsWith=re_)
+# @sensitive
+# @optional # remove this if using resend
+# @docs(https://resend.com/docs/dashboard/api-keys/introduction#what-is-an-api-key)
+RESEND_API_KEY=
+
+# will be set to true when running in CI
+CI=false
+
+# Sentry settings (error tracking) 
+# note that SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_PROJECT are optional
+# but enable @sentry/react-router integration and release tagging
+# ---
+# @type=url
+# @optional # remove this if using sentry
+# @example=https://examplePublicKey@o0.ingest.sentry.io/0
+# @docs(https://docs.sentry.io/concepts/key-terms/dsn-explainer/)
+SENTRY_DSN=
+# @optional @sensitive
+SENTRY_AUTH_TOKEN=
+# @required=if($SENTRY_AUTH_TOKEN)
+SENTRY_ORG=
+# @required=if($SENTRY_AUTH_TOKEN)
+SENTRY_PROJECT=
+
+# GitHub settings
+# 
+# the mocks and some code rely on these being prefixed with "MOCK_"
+# if they aren't then the real github api will be attempted
+# --- 
+GITHUB_CLIENT_ID="MOCK_GITHUB_CLIENT_ID"
+# @sensitive
+GITHUB_CLIENT_SECRET="MOCK_GITHUB_CLIENT_SECRET"
+# @sensitive
+GITHUB_TOKEN="MOCK_GITHUB_TOKEN"
+# @type=url
+GITHUB_REDIRECT_URI="https://example.com/auth/github/callback"
+
+
+# Tigris Object Storage (S3-compatible) Configuration
+# ---
+AWS_ACCESS_KEY_ID="mock-access-key"
+# @sensitive
+AWS_SECRET_ACCESS_KEY="mock-secret-key"
+AWS_REGION="auto"
+# @type=url
+AWS_ENDPOINT_URL_S3="https://fly.storage.tigris.dev"
+BUCKET_NAME="mock-bucket"
+
+# Populated by fly.io
+# ---
+# current fly.io region
+# @optional
+FLY_REGION=
+# app name as set in fly.io
+# @optional
+FLY_APP_NAME=
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 2345034e4..ef74da54f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,8 @@ node_modules
 /build
 /server-build
 .env
+.env.local
+.env.*.local
 .cache
 
 /prisma/data.db
@@ -26,3 +28,4 @@ node_modules
 # generated files
 /app/components/ui/icons
 .react-router/
+/types/env-vars.d.ts
diff --git a/.prettierignore b/.prettierignore
index f022d0280..81afeda3b 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -4,6 +4,7 @@ node_modules
 /public/build
 /server-build
 .env
+.env.*
 
 /test-results/
 /playwright-report/
@@ -11,5 +12,6 @@ node_modules
 /tests/fixtures/email/*.json
 /coverage
 /prisma/migrations
+/types/env-vars.d.ts
 
 package-lock.json
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
index 3c0a690df..7eb65d6b6 100644
--- a/.vscode/extensions.json
+++ b/.vscode/extensions.json
@@ -6,6 +6,7 @@
 		"prisma.prisma",
 		"qwtel.sqlite-viewer",
 		"yoavbls.pretty-ts-errors",
-		"github.vscode-github-actions"
+		"github.vscode-github-actions",
+		"varlock.env-spec-language"
 	]
 }
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4b39faf8c..9c1c0071c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -18,10 +18,9 @@ instructions:
 
 1.  Fork repo
 2.  clone the repo
-3.  Copy `.env.example` into `.env`
-4.  Run `npm install && npm run setup -s` to install dependencies and run
+3.  Run `npm install && npm run setup -s` to install dependencies and run
     validation
-5.  Create a branch for your PR with `git checkout -b pr/your-branch-name`
+4.  Create a branch for your PR with `git checkout -b pr/your-branch-name`
 
 > Tip: Keep your `main` branch pointing at the original repository and make pull
 > requests from branches on your fork. To do this, run:
@@ -44,10 +43,10 @@ If the setup script doesn't work, you can try to run the commands manually:
 git clone <your-fork>
 cd ./epic-stack
 
-# copy the .env.example to .env
+# create a file for gitignored .env overrides
 #   everything's mocked out during development so you shouldn't need to
-#   change any of these values unless you want to hit real environments.
-cp .env.example .env
+#   set anything unless you want to hit real environments.
+touch .env.local
 
 # Install deps
 npm install
diff --git a/app/entry.client.tsx b/app/entry.client.tsx
index 9b7749f3a..69984510f 100644
--- a/app/entry.client.tsx
+++ b/app/entry.client.tsx
@@ -1,6 +1,7 @@
 import { startTransition } from 'react'
 import { hydrateRoot } from 'react-dom/client'
 import { HydratedRouter } from 'react-router/dom'
+import { ENV } from 'varlock/env'
 
 if (ENV.MODE === 'production' && ENV.SENTRY_DSN) {
 	void import('./utils/monitoring.client.tsx').then(({ init }) => init())
diff --git a/app/entry.server.tsx b/app/entry.server.tsx
index 99fdd4b88..f1c7cbda9 100644
--- a/app/entry.server.tsx
+++ b/app/entry.server.tsx
@@ -12,17 +12,13 @@ import {
 	type ActionFunctionArgs,
 	type HandleDocumentRequestFunction,
 } from 'react-router'
-import { getEnv, init } from './utils/env.server.ts'
+import { ENV } from 'varlock/env'
 import { getInstanceInfo } from './utils/litefs.server.ts'
 import { NonceProvider } from './utils/nonce-provider.ts'
 import { makeTimings } from './utils/timing.server.ts'
 
 export const streamTimeout = 5000
 
-init()
-global.ENV = getEnv()
-
-const MODE = process.env.NODE_ENV ?? 'development'
 
 type DocRequestArgs = Parameters<HandleDocumentRequestFunction>
 
@@ -30,12 +26,12 @@ export default async function handleRequest(...args: DocRequestArgs) {
 	const [request, responseStatusCode, responseHeaders, reactRouterContext] =
 		args
 	const { currentInstance, primaryInstance } = await getInstanceInfo()
-	responseHeaders.set('fly-region', process.env.FLY_REGION ?? 'unknown')
-	responseHeaders.set('fly-app', process.env.FLY_APP_NAME ?? 'unknown')
+	responseHeaders.set('fly-region', ENV.FLY_REGION ?? 'unknown')
+	responseHeaders.set('fly-app', ENV.FLY_APP_NAME ?? 'unknown')
 	responseHeaders.set('fly-primary-instance', primaryInstance)
 	responseHeaders.set('fly-instance', currentInstance)
 
-	if (process.env.NODE_ENV === 'production' && process.env.SENTRY_DSN) {
+	if (ENV.NODE_ENV === 'production' && ENV.SENTRY_DSN) {
 		responseHeaders.append('Document-Policy', 'js-profiling')
 	}
 
@@ -72,8 +68,8 @@ export default async function handleRequest(...args: DocRequestArgs) {
 							directives: {
 								fetch: {
 									'connect-src': [
-										MODE === 'development' ? 'ws:' : undefined,
-										process.env.SENTRY_DSN ? '*.sentry.io' : undefined,
+										ENV.MODE === 'development' ? 'ws:' : undefined,
+										ENV.SENTRY_DSN ? '*.sentry.io' : undefined,
 										"'self'",
 									],
 									'font-src': ["'self'"],
@@ -114,8 +110,8 @@ export default async function handleRequest(...args: DocRequestArgs) {
 
 export async function handleDataRequest(response: Response) {
 	const { currentInstance, primaryInstance } = await getInstanceInfo()
-	response.headers.set('fly-region', process.env.FLY_REGION ?? 'unknown')
-	response.headers.set('fly-app', process.env.FLY_APP_NAME ?? 'unknown')
+	response.headers.set('fly-region', ENV.FLY_REGION ?? 'unknown')
+	response.headers.set('fly-app', ENV.FLY_APP_NAME ?? 'unknown')
 	response.headers.set('fly-primary-instance', primaryInstance)
 	response.headers.set('fly-instance', currentInstance)
 
diff --git a/app/root.tsx b/app/root.tsx
index 3b19435c1..93038c125 100644
--- a/app/root.tsx
+++ b/app/root.tsx
@@ -11,6 +11,7 @@ import {
 	useMatches,
 } from 'react-router'
 import { HoneypotProvider } from 'remix-utils/honeypot/react'
+import { ENV } from 'varlock/env'
 import { type Route } from './+types/root.ts'
 import appleTouchIconAssetUrl from './assets/favicons/apple-touch-icon.png'
 import faviconAssetUrl from './assets/favicons/favicon.svg'
@@ -31,7 +32,6 @@ import tailwindStyleSheetUrl from './styles/tailwind.css?url'
 import { getUserId, logout } from './utils/auth.server.ts'
 import { ClientHintCheck, getHints } from './utils/client-hints.tsx'
 import { prisma } from './utils/db.server.ts'
-import { getEnv } from './utils/env.server.ts'
 import { pipeHeaders } from './utils/headers.server.ts'
 import { honeypot } from './utils/honeypot.server.ts'
 import { combineHeaders, getDomainUrl, getImgSrc } from './utils/misc.tsx'
@@ -119,7 +119,6 @@ export async function loader({ request }: Route.LoaderArgs) {
 					theme: getTheme(request),
 				},
 			},
-			ENV: getEnv(),
 			toast,
 			honeyProps,
 		},
@@ -138,14 +137,11 @@ function Document({
 	children,
 	nonce,
 	theme = 'light',
-	env = {},
 }: {
 	children: React.ReactNode
 	nonce: string
 	theme?: Theme
-	env?: Record<string, string | undefined>
 }) {
-	const allowIndexing = ENV.ALLOW_INDEXING !== 'false'
 	return (
 		<html lang="en" className={`${theme} h-full overflow-x-hidden`}>
 			<head>
@@ -153,19 +149,13 @@ function Document({
 				<Meta />
 				<meta charSet="utf-8" />
 				<meta name="viewport" content="width=device-width,initial-scale=1" />
-				{allowIndexing ? null : (
+				{ENV.ALLOW_INDEXING ? null : (
 					<meta name="robots" content="noindex, nofollow" />
 				)}
 				<Links />
 			</head>
 			<body className="bg-background text-foreground">
 				{children}
-				<script
-					nonce={nonce}
-					dangerouslySetInnerHTML={{
-						__html: `window.ENV = ${JSON.stringify(env)}`,
-					}}
-				/>
 				<ScrollRestoration nonce={nonce} />
 				<Scripts nonce={nonce} />
 			</body>
@@ -174,12 +164,10 @@ function Document({
 }
 
 export function Layout({ children }: { children: React.ReactNode }) {
-	// if there was an error running the loader, data could be missing
-	const data = useLoaderData<typeof loader | null>()
 	const nonce = useNonce()
 	const theme = useOptionalTheme()
 	return (
-		<Document nonce={nonce} theme={theme} env={data?.ENV}>
+		<Document nonce={nonce} theme={theme}>
 			{children}
 		</Document>
 	)
diff --git a/app/routes/_auth/auth.$provider/callback.test.ts b/app/routes/_auth/auth.$provider/callback.test.ts
index 10346eb5f..c07b334fc 100644
--- a/app/routes/_auth/auth.$provider/callback.test.ts
+++ b/app/routes/_auth/auth.$provider/callback.test.ts
@@ -2,6 +2,7 @@ import { invariant } from '@epic-web/invariant'
 import { faker } from '@faker-js/faker'
 import { SetCookie } from '@mjackson/headers'
 import { http } from 'msw'
+import { ENV } from 'varlock/env'
 import { afterEach, expect, test } from 'vitest'
 import { twoFAVerificationType } from '#app/routes/settings/profile/two-factor/_layout.tsx'
 import { getSessionExpirationDate, sessionKey } from '#app/utils/auth.server.ts'
@@ -231,7 +232,7 @@ async function setupRequest({
 		sameSite: 'Lax',
 		httpOnly: true,
 		maxAge: 60 * 10,
-		secure: process.env.NODE_ENV === 'production' || undefined,
+		secure: ENV.NODE_ENV === 'production' || undefined,
 	})
 	const request = new Request(url.toString(), {
 		method: 'GET',
diff --git a/app/routes/_auth/webauthn/utils.server.ts b/app/routes/_auth/webauthn/utils.server.ts
index aaaf5fc18..cebe699e3 100644
--- a/app/routes/_auth/webauthn/utils.server.ts
+++ b/app/routes/_auth/webauthn/utils.server.ts
@@ -3,6 +3,7 @@ import {
 	type RegistrationResponseJSON,
 } from '@simplewebauthn/server'
 import { createCookie } from 'react-router'
+import { ENV } from 'varlock/env'
 import { z } from 'zod'
 import { getDomainUrl } from '#app/utils/misc.tsx'
 
@@ -11,8 +12,8 @@ export const passkeyCookie = createCookie('webauthn-challenge', {
 	sameSite: 'lax',
 	httpOnly: true,
 	maxAge: 60 * 60 * 2,
-	secure: process.env.NODE_ENV === 'production',
-	secrets: [process.env.SESSION_SECRET],
+	secure: ENV.NODE_ENV === 'production',
+	secrets: [ENV.SESSION_SECRET],
 })
 
 export const PasskeyCookieSchema = z.object({
diff --git a/app/routes/admin/cache/sqlite.server.ts b/app/routes/admin/cache/sqlite.server.ts
index 721ef8d51..14a85bfb8 100644
--- a/app/routes/admin/cache/sqlite.server.ts
+++ b/app/routes/admin/cache/sqlite.server.ts
@@ -1,4 +1,5 @@
 import { redirect } from 'react-router'
+import { ENV } from 'varlock/env'
 import { z } from 'zod'
 import { cache } from '#app/utils/cache.server.ts'
 import {
@@ -21,7 +22,7 @@ export async function updatePrimaryCacheValue({
 		)
 	}
 	const domain = getInternalInstanceDomain(primaryInstance)
-	const token = process.env.INTERNAL_COMMAND_TOKEN
+	const token = ENV.INTERNAL_COMMAND_TOKEN
 	return fetch(`${domain}/admin/cache/sqlite`, {
 		method: 'POST',
 		headers: {
@@ -39,7 +40,7 @@ export async function action({ request }: Route.ActionArgs) {
 			`${request.url} should only be called on the primary instance (${primaryInstance})}`,
 		)
 	}
-	const token = process.env.INTERNAL_COMMAND_TOKEN
+	const token = ENV.INTERNAL_COMMAND_TOKEN
 	const isAuthorized =
 		request.headers.get('Authorization') === `Bearer ${token}`
 	if (!isAuthorized) {
diff --git a/app/routes/resources/images.tsx b/app/routes/resources/images.tsx
index 766e925d9..ac0cc7ada 100644
--- a/app/routes/resources/images.tsx
+++ b/app/routes/resources/images.tsx
@@ -1,6 +1,7 @@
 import { promises as fs, constants } from 'node:fs'
 import { invariantResponse } from '@epic-web/invariant'
 import { getImgResponse } from 'openimg/node'
+import { ENV } from 'varlock/env'
 import { getDomainUrl } from '#app/utils/misc.tsx'
 import { getSignedGetRequestInfo } from '#app/utils/storage.server.ts'
 import { type Route } from './+types/images'
@@ -11,7 +12,7 @@ async function getCacheDir() {
 	if (cacheDir) return cacheDir
 
 	let dir = './tests/fixtures/openimg'
-	if (process.env.NODE_ENV === 'production') {
+	if (ENV.NODE_ENV === 'production') {
 		const isAccessible = await fs
 			.access('/data', constants.W_OK)
 			.then(() => true)
@@ -38,7 +39,7 @@ export async function loader({ request }: Route.LoaderArgs) {
 		headers,
 		allowlistedOrigins: [
 			getDomainUrl(request),
-			process.env.AWS_ENDPOINT_URL_S3,
+			ENV.AWS_ENDPOINT_URL_S3,
 		].filter(Boolean),
 		cacheFolder: await getCacheDir(),
 		getImgSource: () => {
diff --git a/app/utils/cache.server.ts b/app/utils/cache.server.ts
index 6e26fb93e..85e22466e 100644
--- a/app/utils/cache.server.ts
+++ b/app/utils/cache.server.ts
@@ -14,12 +14,13 @@ import {
 } from '@epic-web/cachified'
 import { remember } from '@epic-web/remember'
 import { LRUCache } from 'lru-cache'
+import { ENV } from 'varlock/env'
 import { z } from 'zod'
 import { updatePrimaryCacheValue } from '#app/routes/admin/cache/sqlite.server.ts'
 import { getInstanceInfo, getInstanceInfoSync } from './litefs.server.ts'
 import { cachifiedTimingReporter, type Timings } from './timing.server.ts'
 
-const CACHE_DATABASE_PATH = process.env.CACHE_DATABASE_PATH
+const CACHE_DATABASE_PATH = ENV.CACHE_DATABASE_PATH
 
 const cacheDb = remember('cacheDb', createDatabase)
 
diff --git a/app/utils/email.server.ts b/app/utils/email.server.ts
index 5ca9264ee..fdf118843 100644
--- a/app/utils/email.server.ts
+++ b/app/utils/email.server.ts
@@ -1,5 +1,6 @@
 import { render } from '@react-email/components'
 import { type ReactElement } from 'react'
+import { ENV } from 'varlock/env'
 import { z } from 'zod'
 
 const resendErrorSchema = z.union([
@@ -40,7 +41,7 @@ export async function sendEmail({
 	}
 
 	// feel free to remove this condition once you've set up resend
-	if (!process.env.RESEND_API_KEY && !process.env.MOCKS) {
+	if (!ENV.RESEND_API_KEY && !ENV.MOCKS) {
 		console.error(`RESEND_API_KEY not set and we're not in mocks mode.`)
 		console.error(
 			`To send emails, set the RESEND_API_KEY environment variable.`,
@@ -56,7 +57,7 @@ export async function sendEmail({
 		method: 'POST',
 		body: JSON.stringify(email),
 		headers: {
-			Authorization: `Bearer ${process.env.RESEND_API_KEY}`,
+			Authorization: `Bearer ${ENV.RESEND_API_KEY}`,
 			'Content-Type': 'application/json',
 		},
 	})
diff --git a/app/utils/env.server.ts b/app/utils/env.server.ts
deleted file mode 100644
index e762b1e60..000000000
--- a/app/utils/env.server.ts
+++ /dev/null
@@ -1,74 +0,0 @@
-import { z } from 'zod'
-
-const schema = z.object({
-	NODE_ENV: z.enum(['production', 'development', 'test'] as const),
-	DATABASE_PATH: z.string(),
-	DATABASE_URL: z.string(),
-	SESSION_SECRET: z.string(),
-	INTERNAL_COMMAND_TOKEN: z.string(),
-	HONEYPOT_SECRET: z.string(),
-	CACHE_DATABASE_PATH: z.string(),
-	// If you plan on using Sentry, remove the .optional()
-	SENTRY_DSN: z.string().optional(),
-	// If you plan to use Resend, remove the .optional()
-	RESEND_API_KEY: z.string().optional(),
-	// If you plan to use GitHub auth, remove the .optional()
-	GITHUB_CLIENT_ID: z.string().optional(),
-	GITHUB_CLIENT_SECRET: z.string().optional(),
-	GITHUB_REDIRECT_URI: z.string().optional(),
-	GITHUB_TOKEN: z.string().optional(),
-
-	ALLOW_INDEXING: z.enum(['true', 'false']).optional(),
-
-	// Tigris Object Storage Configuration
-	AWS_ACCESS_KEY_ID: z.string(),
-	AWS_SECRET_ACCESS_KEY: z.string(),
-	AWS_REGION: z.string(),
-	AWS_ENDPOINT_URL_S3: z.string().url(),
-	BUCKET_NAME: z.string(),
-})
-
-declare global {
-	namespace NodeJS {
-		interface ProcessEnv extends z.infer<typeof schema> {}
-	}
-}
-
-export function init() {
-	const parsed = schema.safeParse(process.env)
-
-	if (parsed.success === false) {
-		console.error(
-			'❌ Invalid environment variables:',
-			parsed.error.flatten().fieldErrors,
-		)
-
-		throw new Error('Invalid environment variables')
-	}
-}
-
-/**
- * This is used in both `entry.server.ts` and `root.tsx` to ensure that
- * the environment variables are set and globally available before the app is
- * started.
- *
- * NOTE: Do *not* add any environment variables in here that you do not wish to
- * be included in the client.
- * @returns all public ENV variables
- */
-export function getEnv() {
-	return {
-		MODE: process.env.NODE_ENV,
-		SENTRY_DSN: process.env.SENTRY_DSN,
-		ALLOW_INDEXING: process.env.ALLOW_INDEXING,
-	}
-}
-
-type ENV = ReturnType<typeof getEnv>
-
-declare global {
-	var ENV: ENV
-	interface Window {
-		ENV: ENV
-	}
-}
diff --git a/app/utils/honeypot.server.ts b/app/utils/honeypot.server.ts
index 55b18a524..d1d0ded9e 100644
--- a/app/utils/honeypot.server.ts
+++ b/app/utils/honeypot.server.ts
@@ -1,8 +1,9 @@
 import { Honeypot, SpamError } from 'remix-utils/honeypot/server'
+import { ENV } from 'varlock/env'
 
 export const honeypot = new Honeypot({
-	validFromFieldName: process.env.NODE_ENV === 'test' ? null : undefined,
-	encryptionSeed: process.env.HONEYPOT_SECRET,
+	validFromFieldName: ENV.NODE_ENV === 'test' ? null : undefined,
+	encryptionSeed: ENV.HONEYPOT_SECRET,
 })
 
 export async function checkHoneypot(formData: FormData) {
diff --git a/app/utils/monitoring.client.tsx b/app/utils/monitoring.client.tsx
index f559b6cbe..fdb99b101 100644
--- a/app/utils/monitoring.client.tsx
+++ b/app/utils/monitoring.client.tsx
@@ -1,4 +1,5 @@
 import * as Sentry from '@sentry/react-router'
+import { ENV } from 'varlock/env'
 
 export function init() {
 	Sentry.init({
diff --git a/app/utils/providers/github.server.ts b/app/utils/providers/github.server.ts
index 1d2cf389b..25015b8f0 100644
--- a/app/utils/providers/github.server.ts
+++ b/app/utils/providers/github.server.ts
@@ -2,6 +2,7 @@ import { SetCookie } from '@mjackson/headers'
 import { createId as cuid } from '@paralleldrive/cuid2'
 import { redirect } from 'react-router'
 import { GitHubStrategy } from 'remix-auth-github'
+import { ENV } from 'varlock/env'
 import { z } from 'zod'
 import { cache, cachified } from '../cache.server.ts'
 import { type Timings } from '../timing.server.ts'
@@ -21,8 +22,8 @@ const GitHubUserParseResult = z
 	)
 
 const shouldMock =
-	process.env.GITHUB_CLIENT_ID?.startsWith('MOCK_') ||
-	process.env.NODE_ENV === 'test'
+	ENV.GITHUB_CLIENT_ID?.startsWith('MOCK_') ||
+	ENV.MODE === 'test'
 
 const GitHubEmailSchema = z.object({
 	email: z.string(),
@@ -43,9 +44,9 @@ const GitHubUserResponseSchema = z.object({
 export class GitHubProvider implements AuthProvider {
 	getAuthStrategy() {
 		if (
-			!process.env.GITHUB_CLIENT_ID ||
-			!process.env.GITHUB_CLIENT_SECRET ||
-			!process.env.GITHUB_REDIRECT_URI
+			!ENV.GITHUB_CLIENT_ID ||
+			!ENV.GITHUB_CLIENT_SECRET ||
+			!ENV.GITHUB_REDIRECT_URI
 		) {
 			console.log(
 				'GitHub OAuth strategy not available because environment variables are not set',
@@ -54,9 +55,9 @@ export class GitHubProvider implements AuthProvider {
 		}
 		return new GitHubStrategy(
 			{
-				clientId: process.env.GITHUB_CLIENT_ID,
-				clientSecret: process.env.GITHUB_CLIENT_SECRET,
-				redirectURI: process.env.GITHUB_REDIRECT_URI,
+				clientId: ENV.GITHUB_CLIENT_ID,
+				clientSecret: ENV.GITHUB_CLIENT_SECRET,
+				redirectURI: ENV.GITHUB_REDIRECT_URI,
 			},
 			async ({ tokens }) => {
 				// we need to fetch the user and the emails separately, this is a change in remix-auth-github
@@ -112,7 +113,7 @@ export class GitHubProvider implements AuthProvider {
 			async getFreshValue(context) {
 				const response = await fetch(
 					`https://api.github.com/user/${providerId}`,
-					{ headers: { Authorization: `token ${process.env.GITHUB_TOKEN}` } },
+					{ headers: { Authorization: `token ${ENV.GITHUB_TOKEN}` } },
 				)
 				const rawJson = await response.json()
 				const result = GitHubUserSchema.safeParse(rawJson)
@@ -147,7 +148,7 @@ export class GitHubProvider implements AuthProvider {
 			sameSite: 'Lax',
 			httpOnly: true,
 			maxAge: 60 * 10,
-			secure: process.env.NODE_ENV === 'production' || undefined,
+			secure: ENV.MODE === 'production' || undefined,
 		})
 		throw redirect(`/auth/github/callback?${searchParams}`, {
 			headers: {
diff --git a/app/utils/session.server.ts b/app/utils/session.server.ts
index 5d9fd3284..4160c02d0 100644
--- a/app/utils/session.server.ts
+++ b/app/utils/session.server.ts
@@ -1,4 +1,5 @@
 import { createCookieSessionStorage } from 'react-router'
+import { ENV } from 'varlock/env'
 
 export const authSessionStorage = createCookieSessionStorage({
 	cookie: {
@@ -6,8 +7,8 @@ export const authSessionStorage = createCookieSessionStorage({
 		sameSite: 'lax', // CSRF protection is advised if changing to 'none'
 		path: '/',
 		httpOnly: true,
-		secrets: process.env.SESSION_SECRET.split(','),
-		secure: process.env.NODE_ENV === 'production',
+		secrets: [ENV.SESSION_SECRET],
+		secure: ENV.NODE_ENV === 'production',
 	},
 })
 
diff --git a/app/utils/storage.server.ts b/app/utils/storage.server.ts
index 2fd7360a9..cf4160eb8 100644
--- a/app/utils/storage.server.ts
+++ b/app/utils/storage.server.ts
@@ -1,12 +1,7 @@
 import { createHash, createHmac } from 'crypto'
 import { type FileUpload } from '@mjackson/form-data-parser'
 import { createId } from '@paralleldrive/cuid2'
-
-const STORAGE_ENDPOINT = process.env.AWS_ENDPOINT_URL_S3
-const STORAGE_BUCKET = process.env.BUCKET_NAME
-const STORAGE_ACCESS_KEY = process.env.AWS_ACCESS_KEY_ID
-const STORAGE_SECRET_KEY = process.env.AWS_SECRET_ACCESS_KEY
-const STORAGE_REGION = process.env.AWS_REGION
+import { ENV } from 'varlock/env'
 
 async function uploadToStorage(file: File | FileUpload, key: string) {
 	const { url, headers } = getSignedPutRequestInfo(file, key)
@@ -85,7 +80,7 @@ function getBaseSignedRequestInfo({
 	contentType?: string
 	uploadDate?: string
 }) {
-	const url = `${STORAGE_ENDPOINT}/${STORAGE_BUCKET}/${key}`
+	const url = `${ENV.AWS_ENDPOINT_URL_S3}/${ENV.BUCKET_NAME}/${key}`
 	const endpoint = new URL(url)
 
 	// Prepare date strings
@@ -106,7 +101,7 @@ function getBaseSignedRequestInfo({
 
 	const canonicalRequest = [
 		method,
-		`/${STORAGE_BUCKET}/${key}`,
+		`/${ENV.BUCKET_NAME}/${key}`,
 		'', // canonicalQueryString
 		canonicalHeaders,
 		signedHeaders,
@@ -115,7 +110,7 @@ function getBaseSignedRequestInfo({
 
 	// Prepare string to sign
 	const algorithm = 'AWS4-HMAC-SHA256'
-	const credentialScope = `${dateStamp}/${STORAGE_REGION}/s3/aws4_request`
+	const credentialScope = `${dateStamp}/${ENV.AWS_REGION}/s3/aws4_request`
 	const stringToSign = [
 		algorithm,
 		amzDate,
@@ -125,9 +120,9 @@ function getBaseSignedRequestInfo({
 
 	// Calculate signature
 	const signingKey = getSignatureKey(
-		STORAGE_SECRET_KEY,
+		ENV.AWS_SECRET_ACCESS_KEY,
 		dateStamp,
-		STORAGE_REGION,
+		ENV.AWS_REGION,
 		's3',
 	)
 	const signature = createHmac('sha256', signingKey)
@@ -138,7 +133,7 @@ function getBaseSignedRequestInfo({
 		'X-Amz-Date': amzDate,
 		'X-Amz-Content-SHA256': 'UNSIGNED-PAYLOAD',
 		Authorization: [
-			`${algorithm} Credential=${STORAGE_ACCESS_KEY}/${credentialScope}`,
+			`${algorithm} Credential=${ENV.AWS_ACCESS_KEY_ID}/${credentialScope}`,
 			`SignedHeaders=${signedHeaders}`,
 			`Signature=${signature}`,
 		].join(', '),
diff --git a/app/utils/toast.server.ts b/app/utils/toast.server.ts
index b46fefa6e..899c2bd50 100644
--- a/app/utils/toast.server.ts
+++ b/app/utils/toast.server.ts
@@ -1,5 +1,6 @@
 import { createId as cuid } from '@paralleldrive/cuid2'
 import { createCookieSessionStorage, redirect } from 'react-router'
+import { ENV } from 'varlock/env'
 import { z } from 'zod'
 import { combineHeaders } from './misc.tsx'
 
@@ -21,8 +22,8 @@ export const toastSessionStorage = createCookieSessionStorage({
 		sameSite: 'lax',
 		path: '/',
 		httpOnly: true,
-		secrets: process.env.SESSION_SECRET.split(','),
-		secure: process.env.NODE_ENV === 'production',
+		secrets: [ENV.SESSION_SECRET],
+		secure: ENV.NODE_ENV === 'production',
 	},
 })
 
diff --git a/app/utils/verification.server.ts b/app/utils/verification.server.ts
index 1099f7c75..856cf70f1 100644
--- a/app/utils/verification.server.ts
+++ b/app/utils/verification.server.ts
@@ -1,4 +1,5 @@
 import { createCookieSessionStorage } from 'react-router'
+import { ENV } from 'varlock/env'
 
 export const verifySessionStorage = createCookieSessionStorage({
 	cookie: {
@@ -7,7 +8,7 @@ export const verifySessionStorage = createCookieSessionStorage({
 		path: '/',
 		httpOnly: true,
 		maxAge: 60 * 10, // 10 minutes
-		secrets: process.env.SESSION_SECRET.split(','),
-		secure: process.env.NODE_ENV === 'production',
+		secrets: [ENV.SESSION_SECRET],
+		secure: ENV.NODE_ENV === 'production',
 	},
 })
diff --git a/docs/authentication.md b/docs/authentication.md
index 4ffedd9d6..115288816 100644
--- a/docs/authentication.md
+++ b/docs/authentication.md
@@ -62,7 +62,7 @@ be redirected to the page with your newly created OAuth app's details. You will
 see your app has got `0` users and no client secrets just yet, but the Client ID
 has already been assigned to your app. Copy over this value to
 `GITHUB_CLIENT_ID` in your _.env_ file. Now hit `Generate client secret` button,
-and copy over the newly generted secret to `GITHUB_CLIENT_SECRET` in the dotenv
+and copy over the newly generated secret to `GITHUB_CLIENT_SECRET` in the .env
 file. Hit `Update application` button on your GitHub OAuth app page.
 
 Your `.env` file should resemble this (values have been redacted):
diff --git a/docs/monitoring.md b/docs/monitoring.md
index ec354fc86..c6af2ecd7 100644
--- a/docs/monitoring.md
+++ b/docs/monitoring.md
@@ -56,9 +56,7 @@ when `npm run build` is run. You may also uncomment and hard code your
 You can do the same for any other secret (environment variable) you need at
 build time, just make sure those secrets (variables) are available on the CI
 runner: see the 'deploy' job from [`deploy`](../.github/workflows/deploy.yml)
-workflow. Note that these do not need to be added to the
-[`env.server`](../app/utils/env.server.ts) env vars schema, as they are only
-used during the build and not the runtime.
+workflow.
 
 The Sentry Vite plugin in [`vite.config.ts`](../vite.config.ts) will create
 sentry releases for you and automatically associate commits during the vite
diff --git a/eslint.config.js b/eslint.config.js
index eede0cf74..df2409301 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -9,6 +9,9 @@ export default [
 		rules: { 'react-hooks/rules-of-hooks': 'off' },
 	},
 	{
-		ignores: ['.react-router/*'],
+		ignores: [
+			'.react-router/*',
+			'types/env-vars.d.ts'
+		],
 	},
 ]
diff --git a/index.js b/index.js
index 082cd60f5..2f51b6dca 100644
--- a/index.js
+++ b/index.js
@@ -1,6 +1,7 @@
-import 'dotenv/config'
+import 'varlock/auto-load'
 import * as fs from 'node:fs'
 import sourceMapSupport from 'source-map-support'
+import { ENV } from 'varlock/env'
 
 sourceMapSupport.install({
 	retrieveSourceMap: function (source) {
@@ -16,11 +17,11 @@ sourceMapSupport.install({
 	},
 })
 
-if (process.env.MOCKS === 'true') {
+if (ENV.MOCKS) {
 	await import('./tests/mocks/index.ts')
 }
 
-if (process.env.NODE_ENV === 'production') {
+if (ENV.MODE === 'production') {
 	await import('./server-build/index.js')
 } else {
 	await import('./server/index.ts')
diff --git a/other/Dockerfile b/other/Dockerfile
index a80103667..4fbdc04f6 100644
--- a/other/Dockerfile
+++ b/other/Dockerfile
@@ -74,7 +74,7 @@ RUN echo "#!/bin/sh\nset -x\nsqlite3 \$CACHE_DATABASE_URL" > /usr/local/bin/cach
 
 WORKDIR /myapp
 
-# Generate random value and save it to .env file which will be loaded by dotenv
+# Generate random value and save it to .env file which will be loaded by varlock
 RUN INTERNAL_COMMAND_TOKEN=$(openssl rand -hex 32) && \
   echo "INTERNAL_COMMAND_TOKEN=$INTERNAL_COMMAND_TOKEN" > .env
 
diff --git a/package-lock.json b/package-lock.json
index 36eaf419a..883125409 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -39,6 +39,7 @@
         "@simplewebauthn/server": "^13.1.1",
         "@tailwindcss/vite": "^4.1.5",
         "@tusbar/cache-control": "1.0.2",
+        "@varlock/vite-integration": "^0.1.0",
         "address": "^2.0.3",
         "bcryptjs": "^3.0.2",
         "class-variance-authority": "^0.7.1",
@@ -48,7 +49,6 @@
         "cookie": "^1.0.2",
         "cross-env": "^7.0.3",
         "date-fns": "^4.1.0",
-        "dotenv": "^16.5.0",
         "execa": "^9.5.2",
         "express": "^4.21.2",
         "express-rate-limit": "^7.5.0",
@@ -77,6 +77,7 @@
         "spin-delay": "^2.0.1",
         "tailwind-merge": "^3.2.0",
         "tailwindcss": "^4.1.5",
+        "varlock": "^0.1.0",
         "vite-env-only": "^3.0.3",
         "zod": "^3.24.4"
       },
@@ -1117,6 +1118,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@env-spec/parser": {
+      "version": "0.0.7",
+      "resolved": "https://registry.npmjs.org/@env-spec/parser/-/parser-0.0.7.tgz",
+      "integrity": "sha512-PK4jVwAZA+5aa3PzVF/We48wA9r1S6GRoZH6oSf/zWvNLc9LErynLbnEmmfLBo67KVqRvaur2a7aBj3H1Mpj2w==",
+      "license": "MIT"
+    },
     "node_modules/@epic-web/cachified": {
       "version": "5.5.2",
       "resolved": "https://registry.npmjs.org/@epic-web/cachified/-/cachified-5.5.2.tgz",
@@ -7396,6 +7403,22 @@
         "win32"
       ]
     },
+    "node_modules/@varlock/vite-integration": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/@varlock/vite-integration/-/vite-integration-0.1.0.tgz",
+      "integrity": "sha512-WXFXDpyV2aUtylxZnVxWRe7pvve1LQbS0BD73Gdio/7D24VK0EVpRXFt6RSeKyzxwLwzvumKVwV6VVIgnkKCjA==",
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^4.4.3"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "varlock": "^0.1.0",
+        "vite": ">=5"
+      }
+    },
     "node_modules/@vitejs/plugin-react": {
       "version": "4.6.0",
       "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-4.6.0.tgz",
@@ -9406,9 +9429,9 @@
       }
     },
     "node_modules/debug": {
-      "version": "4.4.1",
-      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.1.tgz",
-      "integrity": "sha512-KcKCqiftBJcZr++7ykoDIEwSa3XWowTfNPo92BYxjXiyYEVrUQh2aLyhxBCwww+heortUFxEJYcRzosstTEBYQ==",
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
       "license": "MIT",
       "dependencies": {
         "ms": "^2.1.3"
@@ -16281,9 +16304,9 @@
       }
     },
     "node_modules/semver": {
-      "version": "7.7.2",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.2.tgz",
-      "integrity": "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==",
+      "version": "7.7.3",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz",
+      "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==",
       "license": "ISC",
       "bin": {
         "semver": "bin/semver.js"
@@ -17949,6 +17972,49 @@
         "node": "^14.17.0 || ^16.13.0 || >=18.0.0"
       }
     },
+    "node_modules/varlock": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/varlock/-/varlock-0.1.0.tgz",
+      "integrity": "sha512-YDtNfFS01R3WZclQR4amKK3FYToQHCByowpGY//wLwF8Mcq6gfqKwmhIx2TgJ/LgJ9Rf0gaBKal15vr+gHMujQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@env-spec/parser": "^0.0.7",
+        "debug": "^4.4.3",
+        "execa": "^9.6.0",
+        "semver": "^7.7.3",
+        "which": "^5.0.0"
+      },
+      "bin": {
+        "varlock": "bin/cli.js"
+      },
+      "engines": {
+        "node": ">=22"
+      }
+    },
+    "node_modules/varlock/node_modules/isexe": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/isexe/-/isexe-3.1.1.tgz",
+      "integrity": "sha512-LpB/54B+/2J5hqQ7imZHfdU31OlgQqx7ZicVlkm9kzg9/w8GKLEcFfJl/t7DCEDueOyBAD6zCCwTO6Fzs0NoEQ==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/varlock/node_modules/which": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/which/-/which-5.0.0.tgz",
+      "integrity": "sha512-JEdGzHwwkrbWoGOlIHqQ5gtprKGOenpDHpxE9zVR1bWbOtYRyPPHMe9FaP6x61CmNaTThSkb0DAJte5jD+DmzQ==",
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^3.1.1"
+      },
+      "bin": {
+        "node-which": "bin/which.js"
+      },
+      "engines": {
+        "node": "^18.17.0 || >=20.5.0"
+      }
+    },
     "node_modules/vary": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz",
diff --git a/package.json b/package.json
index 006e36fc7..6be62ccbf 100644
--- a/package.json
+++ b/package.json
@@ -13,8 +13,8 @@
     "build": "run-s build:*",
     "build:remix": "react-router build",
     "build:server": "tsx ./other/build-server.ts",
-    "dev": "cross-env NODE_ENV=development MOCKS=true node ./server/dev-server.js",
-    "dev:no-mocks": "cross-env NODE_ENV=development node ./server/dev-server.js",
+    "dev": "cross-env node ./server/dev-server.js",
+    "dev:no-mocks": "cross-env MOCKS=false node ./server/dev-server.js",
     "format": "prettier --write .",
     "lint": "eslint .",
     "setup": "npm run build && prisma migrate deploy && prisma generate --sql && playwright install",
@@ -70,6 +70,7 @@
     "@simplewebauthn/server": "^13.1.1",
     "@tailwindcss/vite": "^4.1.5",
     "@tusbar/cache-control": "1.0.2",
+    "@varlock/vite-integration": "^0.1.0",
     "address": "^2.0.3",
     "bcryptjs": "^3.0.2",
     "class-variance-authority": "^0.7.1",
@@ -79,7 +80,6 @@
     "cookie": "^1.0.2",
     "cross-env": "^7.0.3",
     "date-fns": "^4.1.0",
-    "dotenv": "^16.5.0",
     "execa": "^9.5.2",
     "express": "^4.21.2",
     "express-rate-limit": "^7.5.0",
@@ -108,6 +108,7 @@
     "spin-delay": "^2.0.1",
     "tailwind-merge": "^3.2.0",
     "tailwindcss": "^4.1.5",
+    "varlock": "^0.1.0",
     "vite-env-only": "^3.0.3",
     "zod": "^3.24.4"
   },
diff --git a/playwright.config.ts b/playwright.config.ts
index e5d832d4b..305a149f9 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -1,7 +1,6 @@
+import 'varlock/auto-load'
 import { defineConfig, devices } from '@playwright/test'
-import 'dotenv/config'
-
-const PORT = process.env.PORT || '3000'
+import { ENV } from 'varlock/env'
 
 export default defineConfig({
 	testDir: './tests/e2e',
@@ -10,12 +9,12 @@ export default defineConfig({
 		timeout: 5 * 1000,
 	},
 	fullyParallel: true,
-	forbidOnly: !!process.env.CI,
-	retries: process.env.CI ? 2 : 0,
-	workers: process.env.CI ? 1 : undefined,
+	forbidOnly: !!ENV.CI,
+	retries: ENV.CI ? 2 : 0,
+	workers: ENV.CI ? 1 : undefined,
 	reporter: 'html',
 	use: {
-		baseURL: `http://localhost:${PORT}/`,
+		baseURL: `http://localhost:${ENV.PORT}/`,
 		trace: 'on-first-retry',
 	},
 
@@ -29,13 +28,13 @@ export default defineConfig({
 	],
 
 	webServer: {
-		command: process.env.CI ? 'npm run start:mocks' : 'npm run dev',
-		port: Number(PORT),
+		command: ENV.CI ? 'npm run start:mocks' : 'npm run dev',
+		port: ENV.PORT,
 		reuseExistingServer: true,
 		stdout: 'pipe',
 		stderr: 'pipe',
 		env: {
-			PORT,
+			PORT: ENV.PORT.toString(),
 			NODE_ENV: 'test',
 		},
 	},
diff --git a/prisma.config.ts b/prisma.config.ts
new file mode 100644
index 000000000..8b8f0cf17
--- /dev/null
+++ b/prisma.config.ts
@@ -0,0 +1,9 @@
+// This file will be introduced soon in prisma upgrade PR
+// see https://github.com/epicweb-dev/epic-stack/pull/1059
+
+import 'varlock/auto-load' // this loads DATABASE_URL
+import { defineConfig } from 'prisma/config'
+
+export default defineConfig({
+	earlyAccess: true, // TS type in this prisma version requires this?
+})
\ No newline at end of file
diff --git a/react-router.config.ts b/react-router.config.ts
index 875073799..532ba7788 100644
--- a/react-router.config.ts
+++ b/react-router.config.ts
@@ -1,7 +1,6 @@
 import { type Config } from '@react-router/dev/config'
 import { sentryOnBuildEnd } from '@sentry/react-router'
-
-const MODE = process.env.NODE_ENV
+import { ENV } from 'varlock/env'
 
 export default {
 	// Defaults to true. Set to false to enable SPA for all routes.
@@ -14,7 +13,7 @@ export default {
 	},
 
 	buildEnd: async ({ viteConfig, reactRouterConfig, buildManifest }) => {
-		if (MODE === 'production' && process.env.SENTRY_AUTH_TOKEN) {
+		if (ENV.MODE === 'production' && ENV.SENTRY_AUTH_TOKEN) {
 			await sentryOnBuildEnd({
 				viteConfig,
 				reactRouterConfig,
diff --git a/remix.init/gitignore b/remix.init/gitignore
index 2345034e4..ef74da54f 100644
--- a/remix.init/gitignore
+++ b/remix.init/gitignore
@@ -4,6 +4,8 @@ node_modules
 /build
 /server-build
 .env
+.env.local
+.env.*.local
 .cache
 
 /prisma/data.db
@@ -26,3 +28,4 @@ node_modules
 # generated files
 /app/components/ui/icons
 .react-router/
+/types/env-vars.d.ts
diff --git a/remix.init/index.mjs b/remix.init/index.mjs
index 3ed8d1104..45aefd3bf 100644
--- a/remix.init/index.mjs
+++ b/remix.init/index.mjs
@@ -33,8 +33,7 @@ async function getEpicStackVersion() {
 
 export default async function main({ rootDirectory }) {
 	const FLY_TOML_PATH = path.join(rootDirectory, 'fly.toml')
-	const EXAMPLE_ENV_PATH = path.join(rootDirectory, '.env.example')
-	const ENV_PATH = path.join(rootDirectory, '.env')
+	const ENV_LOCAL_PATH = path.join(rootDirectory, '.env.local')
 	const PKG_PATH = path.join(rootDirectory, 'package.json')
 
 	const appNameRegex = escapeRegExp('epic-stack-template')
@@ -47,16 +46,16 @@ export default async function main({ rootDirectory }) {
 		.replace(/[^a-zA-Z0-9-_]/g, '-')
 		.toLowerCase()
 
-	const [flyTomlContent, env, packageJsonString] = await Promise.all([
+	const [flyTomlContent, packageJsonString] = await Promise.all([
 		fs.readFile(FLY_TOML_PATH, 'utf-8'),
-		fs.readFile(EXAMPLE_ENV_PATH, 'utf-8'),
 		fs.readFile(PKG_PATH, 'utf-8'),
 	])
 
-	const newEnv = env.replace(
-		/^SESSION_SECRET=.*$/m,
+	let newEnvLocal = [
+		`# Git-ignored env var overrides for local development`,
+		'',
 		`SESSION_SECRET="${getRandomString(16)}"`,
-	)
+	].join('\n')
 
 	const newFlyTomlContent = flyTomlContent.replace(
 		new RegExp(appNameRegex, 'g'),
@@ -82,7 +81,7 @@ export default async function main({ rootDirectory }) {
 
 	const fileOperationPromises = [
 		fs.writeFile(FLY_TOML_PATH, newFlyTomlContent),
-		fs.writeFile(ENV_PATH, newEnv),
+		fs.writeFile(ENV_LOCAL_PATH, newEnvLocal),
 		fs.writeFile(PKG_PATH, JSON.stringify(packageJson, null, 2) + '\n'),
 		fs.copyFile(
 			path.join(rootDirectory, 'remix.init', 'gitignore'),
@@ -363,3 +362,5 @@ async function makeFlyRequest({ query, variables }) {
 	}).then((response) => response.json())
 	return json.data
 }
+
+main({ rootDirectory: process.cwd() })
diff --git a/server/dev-server.js b/server/dev-server.js
index 026131986..b8618c7d2 100644
--- a/server/dev-server.js
+++ b/server/dev-server.js
@@ -1,5 +1,6 @@
 import { execa } from 'execa'
 
+// using process.env because we have not loaded varlock yet
 if (process.env.NODE_ENV === 'production') {
 	await import('../server-build/index.js')
 } else {
diff --git a/server/index.ts b/server/index.ts
index b3103284c..2290128fe 100644
--- a/server/index.ts
+++ b/server/index.ts
@@ -10,12 +10,11 @@ import rateLimit from 'express-rate-limit'
 import getPort, { portNumbers } from 'get-port'
 import morgan from 'morgan'
 import { type ServerBuild } from 'react-router'
+import { ENV } from 'varlock/env'
 
-const MODE = process.env.NODE_ENV ?? 'development'
-const IS_PROD = MODE === 'production'
-const IS_DEV = MODE === 'development'
-const ALLOW_INDEXING = process.env.ALLOW_INDEXING !== 'false'
-const SENTRY_ENABLED = IS_PROD && process.env.SENTRY_DSN
+const IS_PROD = ENV.MODE === 'production'
+const IS_DEV = ENV.MODE === 'development'
+const SENTRY_ENABLED = IS_PROD && ENV.SENTRY_DSN
 
 if (SENTRY_ENABLED) {
 	void import('./utils/monitoring.js').then(({ init }) => init())
@@ -190,7 +189,7 @@ async function getBuild() {
 	}
 }
 
-if (!ALLOW_INDEXING) {
+if (!ENV.ALLOW_INDEXING) {
 	app.use((_, res, next) => {
 		res.set('X-Robots-Tag', 'noindex, nofollow')
 		next()
@@ -201,7 +200,7 @@ app.all(
 	'*',
 	createRequestHandler({
 		getLoadContext: () => ({ serverBuild: getBuild() }),
-		mode: MODE,
+		mode: ENV.MODE,
 		build: async () => {
 			const { error, build } = await getBuild()
 			// gracefully "catch" the error
@@ -213,7 +212,7 @@ app.all(
 	}),
 )
 
-const desiredPort = Number(process.env.PORT || 3000)
+const desiredPort = ENV.PORT
 const portToUse = await getPort({
 	port: portNumbers(desiredPort, desiredPort + 100),
 })
diff --git a/server/utils/monitoring.ts b/server/utils/monitoring.ts
index 107521a10..c3bd9935e 100644
--- a/server/utils/monitoring.ts
+++ b/server/utils/monitoring.ts
@@ -1,11 +1,12 @@
 import { PrismaInstrumentation } from '@prisma/instrumentation'
 import { nodeProfilingIntegration } from '@sentry/profiling-node'
 import * as Sentry from '@sentry/react-router'
+import { ENV } from 'varlock/env'
 
 export function init() {
 	Sentry.init({
-		dsn: process.env.SENTRY_DSN,
-		environment: process.env.NODE_ENV,
+		dsn: ENV.SENTRY_DSN,
+		environment: ENV.NODE_ENV,
 		denyUrls: [
 			/\/resources\/healthcheck/,
 			// TODO: be smarter about the public assets...
@@ -28,7 +29,7 @@ export function init() {
 			if (samplingContext.request?.url?.includes('/resources/healthcheck')) {
 				return 0
 			}
-			return process.env.NODE_ENV === 'production' ? 1 : 0
+			return ENV.NODE_ENV === 'production' ? 1 : 0
 		},
 		beforeSendTransaction(event) {
 			// ignore all healthcheck related transactions
diff --git a/tests/mocks/github.ts b/tests/mocks/github.ts
index 936aeec3a..9ccf0db44 100644
--- a/tests/mocks/github.ts
+++ b/tests/mocks/github.ts
@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { faker } from '@faker-js/faker'
 import fsExtra from 'fs-extra'
 import { HttpResponse, passthrough, http, type HttpHandler } from 'msw'
+import { ENV } from 'varlock/env'
 import { USERNAME_MAX_LENGTH } from '#app/utils/user-validation.ts'
 
 const { json } = HttpResponse
@@ -129,8 +130,8 @@ async function getUser(request: Request) {
 }
 
 const passthroughGitHub =
-	!process.env.GITHUB_CLIENT_ID?.startsWith('MOCK_') &&
-	process.env.NODE_ENV !== 'test'
+	!ENV.GITHUB_CLIENT_ID?.startsWith('MOCK_') &&
+	ENV.NODE_ENV !== 'test'
 
 export const handlers: Array<HttpHandler> = [
 	http.post(
diff --git a/tests/mocks/index.ts b/tests/mocks/index.ts
index 441f3f039..a6261103a 100644
--- a/tests/mocks/index.ts
+++ b/tests/mocks/index.ts
@@ -1,5 +1,6 @@
 import closeWithGrace from 'close-with-grace'
 import { setupServer } from 'msw/node'
+import { ENV } from 'varlock/env';
 import { handlers as githubHandlers } from './github.ts'
 import { handlers as pwnedPasswordApiHandlers } from './pwned-passwords.ts'
 import { handlers as resendHandlers } from './resend.ts'
@@ -30,7 +31,7 @@ server.listen({
 	},
 })
 
-if (process.env.NODE_ENV !== 'test') {
+if (ENV.NODE_ENV !== 'test') {
 	console.info('🔶 Mock server installed')
 
 	closeWithGrace(() => {
diff --git a/tests/mocks/tigris.ts b/tests/mocks/tigris.ts
index b8f2d1700..3c45229db 100644
--- a/tests/mocks/tigris.ts
+++ b/tests/mocks/tigris.ts
@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url'
 import { invariantResponse } from '@epic-web/invariant'
 import { lookup as getMimeType } from 'mime-types'
 import { http, HttpResponse } from 'msw'
+import { ENV } from 'varlock/env'
 
 // Ensure we have a valid URL by explicitly creating it from the import.meta.url
 const __filename = fileURLToPath(import.meta.url)
@@ -12,9 +13,9 @@ const __dirname = path.dirname(__filename)
 const FIXTURES_DIR = path.join(__dirname, '..', 'fixtures')
 const MOCK_STORAGE_DIR = path.join(FIXTURES_DIR, 'uploaded')
 const FIXTURES_IMAGES_DIR = path.join(FIXTURES_DIR, 'images')
-const STORAGE_ENDPOINT = process.env.AWS_ENDPOINT_URL_S3
-const STORAGE_BUCKET = process.env.BUCKET_NAME
-const STORAGE_ACCESS_KEY = process.env.AWS_ACCESS_KEY_ID
+const STORAGE_ENDPOINT = ENV.AWS_ENDPOINT_URL_S3
+const STORAGE_BUCKET = ENV.BUCKET_NAME
+const STORAGE_ACCESS_KEY = ENV.AWS_ACCESS_KEY_ID
 
 function validateAuth(headers: Headers) {
 	const authHeader = headers.get('Authorization')
diff --git a/tests/setup/global-setup.ts b/tests/setup/global-setup.ts
index a81d74d30..8ab171762 100644
--- a/tests/setup/global-setup.ts
+++ b/tests/setup/global-setup.ts
@@ -1,8 +1,7 @@
+import 'varlock/auto-load'
 import path from 'node:path'
 import { execaCommand } from 'execa'
 import fsExtra from 'fs-extra'
-import 'dotenv/config'
-import '#app/utils/env.server.ts'
 import '#app/utils/cache.server.ts'
 
 export const BASE_DATABASE_PATH = path.join(
diff --git a/tests/setup/setup-test-env.ts b/tests/setup/setup-test-env.ts
index 8987c439c..4a3f3e4b1 100644
--- a/tests/setup/setup-test-env.ts
+++ b/tests/setup/setup-test-env.ts
@@ -1,6 +1,5 @@
-import 'dotenv/config'
+import 'varlock/auto-load'
 import './db-setup.ts'
-import '#app/utils/env.server.ts'
 // we need these to be imported first 👆
 
 import { cleanup } from '@testing-library/react'
diff --git a/vite.config.ts b/vite.config.ts
index 1f10a67c9..6d56c3e48 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -1,20 +1,22 @@
+
 import { reactRouter } from '@react-router/dev/vite'
 import {
 	type SentryReactRouterBuildOptions,
 	sentryReactRouter,
 } from '@sentry/react-router'
 import tailwindcss from '@tailwindcss/vite'
+import { varlockVitePlugin } from '@varlock/vite-integration'
 import { reactRouterDevTools } from 'react-router-devtools'
+import { ENV } from 'varlock/env'
 import { defineConfig } from 'vite'
 import { envOnlyMacros } from 'vite-env-only'
 import { iconsSpritesheet } from 'vite-plugin-icons-spritesheet'
 
-const MODE = process.env.NODE_ENV
 
 export default defineConfig((config) => ({
 	build: {
 		target: 'es2022',
-		cssMinify: MODE === 'production',
+		cssMinify: ENV.MODE === 'production',
 
 		rollupOptions: {
 			external: [/node:.*/, 'fsevents'],
@@ -38,6 +40,7 @@ export default defineConfig((config) => ({
 	},
 	sentryConfig,
 	plugins: [
+		varlockVitePlugin(),
 		envOnlyMacros(),
 		tailwindcss(),
 		reactRouterDevTools(),
@@ -51,8 +54,8 @@ export default defineConfig((config) => ({
 		}),
 		// it would be really nice to have this enabled in tests, but we'll have to
 		// wait until https://github.com/remix-run/remix/issues/9871 is fixed
-		MODE === 'test' ? null : reactRouter(),
-		MODE === 'production' && process.env.SENTRY_AUTH_TOKEN
+		ENV.MODE === 'test' ? null : reactRouter(),
+		ENV.MODE === 'production' && ENV.SENTRY_AUTH_TOKEN
 			? sentryReactRouter(sentryConfig, config)
 			: null,
 	],
@@ -69,13 +72,13 @@ export default defineConfig((config) => ({
 }))
 
 const sentryConfig: SentryReactRouterBuildOptions = {
-	authToken: process.env.SENTRY_AUTH_TOKEN,
-	org: process.env.SENTRY_ORG,
-	project: process.env.SENTRY_PROJECT,
+	authToken: ENV.SENTRY_AUTH_TOKEN,
+	org: ENV.SENTRY_ORG,
+	project: ENV.SENTRY_PROJECT,
 
 	unstable_sentryVitePluginOptions: {
 		release: {
-			name: process.env.COMMIT_SHA,
+			name: ENV.COMMIT_SHA,
 			setCommits: {
 				auto: true,
 			},