Configuration model
Why a few settings live in environment variables and everything else lives in the database, edited in the admin console.
Kernlift keeps settings in two places. A handful of environment variables start the app and connect it to the database. Everything else, including every provider credential, is stored in the database and edited in the admin console. To change settings, see Manage configuration.
The rule
| Setting | Where it goes | Why |
|---|---|---|
| App environment, session secret, database connection, site URL | .env or your host's environment | Needed before the app can read the database |
| Sign-in methods, email, payments, storage, AI, analytics, cache | Admin console, /admin/config/* | Stored in the database, changed without a redeploy |
| Products, plans and licences | Admin console, /admin/products and /admin/licences | Business data, not configuration |
The split follows startup order. Anything the process needs before it can open the database comes from the environment. Everything else is stored in the database and managed by the operator.
Why provider settings are not environment variables
- No redeploy to change a provider. Rotating a key, switching the active email provider or turning on Google sign-in takes one save in the admin console.
- One source of truth. The
/setupchecklist, the admin pages and the runtime all read the same rows, so the page reports the configuration the server uses. - A forkable template. A project built on the template adds provider settings to the admin
surface and adds no environment variable. Feature code does not read
process.env.
The environment variables
A local project needs only BETTER_AUTH_SECRET, which you set in the quick start. Production sets
these:
| Variable | Role |
|---|---|
APP_ENV | development or production. Production enables stricter checks |
BETTER_AUTH_SECRET | Signs sessions. Production refuses to start with the template default |
CONFIG_ENCRYPTION_KEY | Optional, strongly recommended. Encrypts the credentials stored in the database; see Encrypt stored credentials |
DATABASE_DIALECT | sqlite, postgres or d1 |
DATABASE_ADAPTER | Optional adapter id such as turso or a custom adapter. Defaults to the dialect |
DATABASE_URL | File path or connection string |
SITE_URL | Canonical origin for metadata, the sitemap, the feed and email links |
.env.example lists every variable the source reads, and pnpm validate:env-example keeps the two in
step. Every variable is described in Environment variables.
The admin settings pages
| Page | Covers |
|---|---|
/admin/config/auth | Email and password rules, Google and GitHub OAuth, Google One Tap, the sign-up bonus |
/admin/config/email | Resend, Cloudflare Email or Aliyun DirectMail, and notification webhooks |
/admin/config/payment | Stripe, Creem, PayPal, DodoPayments, WeChat Pay, Alipay or Waffo, success and cancel URLs, promotion codes |
/admin/config/storage | S3-compatible storage and allowed upload types |
/admin/config/ai | AI providers, provider scenes, scenes and credit pricing |
/admin/config/analytics | Analytics provider |
/admin/config/cache | Cache enable, TTL and backend per domain |
/admin/config/sandbox | Agent sandbox provider, image and resource limits; installed with agent-starter |
/admin/config/search | Agent search and crawl services; installed with agent-starter |
Newsletter, notification channels and rate limits have separate admin pages. The complete route and permission map is in Manage configuration.
"Not configured" is a state, not an error
A provider without credentials reports "not configured" and does not run. The template never fakes
a provider response, simulates a payment or invents usage data. /setup turns those states into a
checklist: each item is Ready or Not ready, and Configure links to the page that fixes it.
Only the session secret, a sign-in method and email delivery are required.
Encrypt stored credentials
Credentials live in the database, so a leaked backup, read replica or database console would expose
them. Set CONFIG_ENCRYPTION_KEY (at least 32 characters) in the environment of every process that
reads the config table, the web app and, when deployed, the Agent service, and every setting classified
secret is encrypted at rest:
- What is encrypted. Values classified
secret: payment, email, storage, AI and OAuth credentials. They are written asenc:v1:<iv>:<ciphertext>with AES-256-GCM, the key derived with HKDF-SHA-256 and the setting key bound as additional data, so a ciphertext cannot be moved to another row.publicandinternalvalues stay plaintext. - Existing credentials. A credential saved before the key was set stays plaintext until it is saved
again. Run
pnpm db:encrypt-config-secretsonce to encrypt them all; on D1 add--remotefor the deployed database. A second run changes nothing. - A wrong or missing key. A value that cannot be decrypted reads as not configured, never as ciphertext, and seeding never overwrites it, so restoring the right key restores the credential.
- Caches. Cache domains that hold decrypted credentials always use process memory; KV or Redis
cannot be chosen for them on
/admin/config/cache. - Readiness.
/setuphas a Credential encryption item. It reports a missing or too short key, plaintext credentials left over and credentials that cannot be decrypted; only the last makes it required.
Without the key, credentials are stored as plaintext and everything else behaves the same, which suits
local development. kernlift deploy-target generates the key into .env.production. Keep the key
stable: there is no rotation, and changing or losing it means entering every credential again.
How settings are read
Most configuration reads are cached. Saving through the console clears the relevant domain. A direct database edit may remain unseen until its TTL expires. The bootstrap admin_config cache cannot read its own policy from the table it caches, so its TTL comes from ADMIN_CONFIG_CACHE_TTL_MS. /admin/config/cache marks that domain as not configurable.
Variables outside the application
The KERNLIFT_* variables at the end of .env.example are read only by the registry publishing
script and the CLI's package commands. The application never reads them, and a project cloned from
GitHub can leave them unset.
Files
The pages use shared console patterns, but their data is not all stored alike: ordinary provider settings use classified config_settings rows, AI channels and pricing use dedicated tables, and Agent search uses JSON rows classified as secret.
Next steps
Deployment model
One platform per project, two build targets, which databases and agent setups each platform allows, where secrets live, when migrations run, and how scheduled jobs are started.
Configure a working project
Set startup variables, make sign-in and email work, then connect and verify the providers your product uses.