Environment variables
The six variables a deployment needs, the few optional ones, and the variables only the agent service and the scripts read.
A running site needs six environment variables. Everything else, including provider credentials, sign-in methods, the sender address and payment settings, is set in /admin/config/* and stored in the database. .env.example lists every variable the source reads, and pnpm validate:env-example fails when the two disagree.
Required
| Variable | Default | Purpose |
|---|---|---|
APP_ENV | development | development or production. Anything other than development enables the production guards |
BETTER_AUTH_SECRET | Template secret (development only) | Session signing key. Outside development, an empty value or the template default stops the app |
SITE_URL | https://kernlift.example.com | Canonical origin for metadata, the sitemap, the feed and absolute links |
DATABASE_DIALECT | sqlite | sqlite, postgres or d1; also selects the migration chain |
DATABASE_URL | ./local.db (empty for postgres) | File path, postgresql:// or libsql:// URL |
Optional
Leave these unset unless you need what they do.
| Variable | Default | Purpose |
|---|---|---|
CONFIG_ENCRYPTION_KEY | — (credentials stored in plaintext) | At least 32 characters. Encrypts admin config values classified secret (payment, email, storage, AI and OAuth credentials) at rest with AES-256-GCM, stored as enc:v1:…. Keep it stable: a value written with one key reads as not configured under another. Run pnpm db:encrypt-config-secrets once to encrypt credentials saved before the key was set. See Encrypt stored credentials |
JOBS_IN_PROCESS | true | A Node server runs the scheduled jobs inside the web process once a minute. Set false to leave them to an external cron calling pnpm jobs:run. A Cloudflare Worker does not read it and uses the Cron Trigger in wrangler.jsonc |
ADMIN_CONFIG_CACHE_TTL_MS | 30000 | Cache lifetime for admin config, the one cache that cannot read its own policy from /admin/config/cache |
DATABASE_ADAPTER | The dialect | Registered adapter id: sqlite, postgres, turso, d1, hyperdrive (Postgres from a Worker) or a custom one |
DATABASE_AUTH_TOKEN | — | libSQL auth token for the turso adapter |
AUTH_DEV_IMPERSONATE_USER_ID | — | Treat unauthenticated requests as this user. Works only while APP_ENV=development and logs a warning |
Optional Agent service
Set these only when you deploy the Agent service next to the web app. A site without it needs none of them. Model, sandbox and search settings are configured in /admin/config/*. Locally, pnpm dev:agent sets the addresses and generates the two secrets for each run; a deployment needs fixed values.
| Variable | Default | Read by | Purpose |
|---|---|---|---|
AGENT_SERVICE_URL | — | Web app | Internal URL of the Agent service. Required for the agent on a Node deployment; a Cloudflare deployment reaches its container through the AGENT_SERVICE binding instead |
AGENT_WEB_INTERNAL_URL | — | Agent service | Internal URL of the web app. Required |
AGENT_INTERNAL_SIGNING_SECRET | — | Both | Signs requests between the two processes; same value on both, at least 32 bytes. Required |
AGENT_RESOURCE_GRANT_SECRET | — | Web app | Signs short-lived resource grants; at least 32 bytes. Required |
AGENT_SERVICE_HOST, AGENT_SERVICE_PORT | ::, 3001 | Agent service | Listen address and port |
AGENT_SERVICE_REQUEST_TIMEOUT_MS | 120000 | Web app | Timeout for a dispatch to the Agent service |
AGENT_FLOW_LOG_LEVEL | info | Both | debug, info, warn, error or silent |
AGENT_SANDBOX_ERROR_LOG_ENABLED | true | Agent service | Logs sandbox error details |
The Agent service refuses to start with web authentication or payment secrets in its environment. Give it the same CONFIG_ENCRYPTION_KEY as the web app, because it reads the same config table. Its database must support transactions, so D1 cannot hold Agent data. See install Agent.
Scripts and tooling
Read by command-line scripts and validators only. The web app never reads them.
| Variable | Read by | Purpose |
|---|---|---|
SUPER_ADMIN_EMAIL, SUPER_ADMIN_PASSWORD | pnpm db:bootstrap-super-admin | Required. First administrator; the password (8+ characters) is used only when the account is created |
SUPER_ADMIN_NAME | pnpm db:bootstrap-super-admin | Optional; defaults to Super Admin |
EXTERNAL_VALIDATE_STRICT | pnpm validate:external | true turns skipped provider checks into failures |
EXTERNAL_VALIDATE_EMAIL_TO | pnpm validate:external | Recipient for the real email check |
EXTERNAL_VALIDATE_NEWSLETTER_EMAIL | pnpm validate:external | Address subscribed and unsubscribed through the newsletter provider |
EXTERNAL_VALIDATE_GOOGLE_OAUTH_CONFIRMED | pnpm validate:external | Confirms a manual Google OAuth sign-in was completed |
EXTERNAL_VALIDATE_BILLING_CUSTOMER_ID, EXTERNAL_VALIDATE_BILLING_PAYMENT_ID, EXTERNAL_VALIDATE_BILLING_SUBSCRIPTION_ID | pnpm validate:external | Sandbox ids for portal, refund and subscription checks |
KERNLIFT_REGISTRY_URL, KERNLIFT_PUBLISH_TOKEN | pnpm registry:publish | Registry to publish to and its publishing key. Not used by a cloned project |
KERNLIFT_TOKEN, KERNLIFT_CONFIG_DIR | The CLI's package commands | Registry token and config directory override. Not used by a cloned project |
CHROME_PATH | pnpm assets:screenshots | Chrome executable for screenshot capture |
NODE_ENV | Database scripts | Provided by the tooling; selects which .env files are loaded |
AGENT_DEV_WEB_HOST, AGENT_DEV_WEB_PORT | pnpm dev:agent | Web listener for local development; default 127.0.0.1:5173 |
AGENT_DEV_SERVICE_HOST, AGENT_DEV_SERVICE_PORT | pnpm dev:agent | Agent service listener for local development; default 127.0.0.1:3001 |
SKILL_PUBLISH_DRY_RUN | pnpm agent:publish-skills | Any non-empty value reports what would be published and writes nothing |
AGENT_SANDBOX_TEMPLATE_DIR | Sandbox image build | Overrides the sandbox image template directory |
Cloudflare bindings
These are declared in wrangler.jsonc. They do not go in .env.
| Binding | Type | Purpose |
|---|---|---|
EDGE_DB | D1 database | Database for the d1 adapter |
HYPERDRIVE | Hyperdrive | Postgres connection for the hyperdrive adapter; commented out until you use Postgres on a Worker |
BUCKET | R2 bucket | Storage through the bucket binding driver |
CACHE | KV namespace | The kv cache backend |
AI | Workers AI | Edge inference |
ASSETS | Static assets | Serves dist/client |
wrangler.jsonc also declares "triggers": { "crons": ["* * * * *"] }, which starts the scheduled jobs once a minute. When the Agent service runs as a Cloudflare container, its direct Postgres URL is the Worker secret AGENT_DATABASE_URL, set with wrangler secret put.
Not environment variables
Provider settings such as RESEND_API_KEY, STRIPE_SECRET_KEY or GOOGLE_CLIENT_ID have no effect: set them in the admin console, as described in Configure a working project. AI channel request templates in /admin/config/ai may reference a variable as {{env.NAME}}; secrets use {{secret.KEY}}.
Next steps
Validators
Every validate:* script, what it proves, whether validate:all and the release gate run it, and which ones are known to fail.
Deployment configuration
deploy.config.json and the kernlift deploy-target command that rewrites it: the combinations it allows, the files each platform owns, the keys of .env.production, and how each platform migrates and bootstraps.