Kernlift

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

VariableDefaultPurpose
APP_ENVdevelopmentdevelopment or production. Anything other than development enables the production guards
BETTER_AUTH_SECRETTemplate secret (development only)Session signing key. Outside development, an empty value or the template default stops the app
SITE_URLhttps://kernlift.example.comCanonical origin for metadata, the sitemap, the feed and absolute links
DATABASE_DIALECTsqlitesqlite, 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.

VariableDefaultPurpose
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_PROCESStrueA 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_MS30000Cache lifetime for admin config, the one cache that cannot read its own policy from /admin/config/cache
DATABASE_ADAPTERThe dialectRegistered 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.

VariableDefaultRead byPurpose
AGENT_SERVICE_URL—Web appInternal 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 serviceInternal URL of the web app. Required
AGENT_INTERNAL_SIGNING_SECRET—BothSigns requests between the two processes; same value on both, at least 32 bytes. Required
AGENT_RESOURCE_GRANT_SECRET—Web appSigns short-lived resource grants; at least 32 bytes. Required
AGENT_SERVICE_HOST, AGENT_SERVICE_PORT::, 3001Agent serviceListen address and port
AGENT_SERVICE_REQUEST_TIMEOUT_MS120000Web appTimeout for a dispatch to the Agent service
AGENT_FLOW_LOG_LEVELinfoBothdebug, info, warn, error or silent
AGENT_SANDBOX_ERROR_LOG_ENABLEDtrueAgent serviceLogs 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.

VariableRead byPurpose
SUPER_ADMIN_EMAIL, SUPER_ADMIN_PASSWORDpnpm db:bootstrap-super-adminRequired. First administrator; the password (8+ characters) is used only when the account is created
SUPER_ADMIN_NAMEpnpm db:bootstrap-super-adminOptional; defaults to Super Admin
EXTERNAL_VALIDATE_STRICTpnpm validate:externaltrue turns skipped provider checks into failures
EXTERNAL_VALIDATE_EMAIL_TOpnpm validate:externalRecipient for the real email check
EXTERNAL_VALIDATE_NEWSLETTER_EMAILpnpm validate:externalAddress subscribed and unsubscribed through the newsletter provider
EXTERNAL_VALIDATE_GOOGLE_OAUTH_CONFIRMEDpnpm validate:externalConfirms a manual Google OAuth sign-in was completed
EXTERNAL_VALIDATE_BILLING_CUSTOMER_ID, EXTERNAL_VALIDATE_BILLING_PAYMENT_ID, EXTERNAL_VALIDATE_BILLING_SUBSCRIPTION_IDpnpm validate:externalSandbox ids for portal, refund and subscription checks
KERNLIFT_REGISTRY_URL, KERNLIFT_PUBLISH_TOKENpnpm registry:publishRegistry to publish to and its publishing key. Not used by a cloned project
KERNLIFT_TOKEN, KERNLIFT_CONFIG_DIRThe CLI's package commandsRegistry token and config directory override. Not used by a cloned project
CHROME_PATHpnpm assets:screenshotsChrome executable for screenshot capture
NODE_ENVDatabase scriptsProvided by the tooling; selects which .env files are loaded
AGENT_DEV_WEB_HOST, AGENT_DEV_WEB_PORTpnpm dev:agentWeb listener for local development; default 127.0.0.1:5173
AGENT_DEV_SERVICE_HOST, AGENT_DEV_SERVICE_PORTpnpm dev:agentAgent service listener for local development; default 127.0.0.1:3001
SKILL_PUBLISH_DRY_RUNpnpm agent:publish-skillsAny non-empty value reports what would be published and writes nothing
AGENT_SANDBOX_TEMPLATE_DIRSandbox image buildOverrides the sandbox image template directory

Cloudflare bindings

These are declared in wrangler.jsonc. They do not go in .env.

BindingTypePurpose
EDGE_DBD1 databaseDatabase for the d1 adapter
HYPERDRIVEHyperdrivePostgres connection for the hyperdrive adapter; commented out until you use Postgres on a Worker
BUCKETR2 bucketStorage through the bucket binding driver
CACHEKV namespaceThe kv cache backend
AIWorkers AIEdge inference
ASSETSStatic assetsServes 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