Environment configuration

Set the variables your Ownfold integrations validate internally at server startup.

Ownfold packages use T3 Env internally to parse server configuration. Applications only set the documented variables in .env, the deployment platform, or the process environment. Do not install or configure @t3-oss/env-core or Valibot in the application for Ownfold.

Provider resolvers validate their own variables when constructed. Other server concerns expose typed readers from @ownfold/server:

import {
  readHttpListenerEnvironment,
  readPostgresEnvironment,
} from "@ownfold/server"

export const databaseEnvironment = readPostgresEnvironment()
export const listenerEnvironment = readHttpListenerEnvironment()

The readers return normalized, typed values and fail before a server or integration is created. Keep this module server-only. Ownfold currently requires no public browser environment variables.

Variable inventory

Only set variables used by the selected stack:

Area	Variables	Notes
Better Auth	`BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`	Both are required. The secret must contain at least 32 characters; the URL must be an exact origin. `betterAuthUserResolver()` validates them automatically.
WorkOS AuthKit	Required `WORKOS_CLIENT_ID`, `WORKOS_API_KEY`, `WORKOS_REDIRECT_URI`, `WORKOS_COOKIE_PASSWORD`; optional `WORKOS_API_HOSTNAME`, `WORKOS_API_HTTPS`, `WORKOS_API_PORT`, `WORKOS_COOKIE_MAX_AGE`, `WORKOS_COOKIE_NAME`, `WORKOS_COOKIE_DOMAIN`, `WORKOS_COOKIE_SAME_SITE`	The cookie password must contain at least 32 characters. `workosAuthKitUserResolver()` validates them automatically.
Auth.js v4	`NEXTAUTH_SECRET`, `NEXTAUTH_URL`, optional paired `GITHUB_ID` and `GITHUB_SECRET`	Configure both GitHub values or neither. `authJsUserResolver()` validates them automatically.
Ownfold passkey access	`OWNFOLD_WEBAUTHN_RP_ID`, `OWNFOLD_WEBAUTHN_RP_NAME`, `OWNFOLD_WEBAUTHN_ORIGINS`	Required by `createPasskeyVaultServerFromEnvironment()`. Origins are a comma-separated exact HTTPS allowlist; explicit loopback HTTP is accepted for development.
PostgreSQL	`DATABASE_URL`, optional `DATABASE_SSL=disable\|require`	`readPostgresEnvironment()` requires a `postgres:` or `postgresql:` URL.
SQLite	Optional `OWNFOLD_DATABASE_PATH`	`readSqliteEnvironment()` defaults to `ownfold.sqlite`. Use `:memory:` only in tests.
HTTP service	`APP_ORIGIN`, optional `HOST` and `PORT`	Use `readHttpEnvironment()` when an exact public origin is needed, or `readHttpListenerEnvironment()` for listener settings only.
Static bearer examples	`API_BEARER_TOKEN`, `OWNFOLD_USER_ID`	Demonstration boundary only, read by `readStaticIdentityEnvironment()`. Replace this with real authentication in production.
Node runtime	Optional `NODE_ENV=development\|production\|test`	Read by `readNodeEnvironment()`; defaults to `development`.
Repository PostgreSQL tests	`OWNFOLD_TEST_POSTGRES_URL`	Repository tooling only. It must target a local database named exactly `ownfold_test`.

Provider versions can introduce variables unrelated to Ownfold. Configure those according to the provider documentation. Ownfold validates the variables it consumes or relies on for its integration boundary.

Deployment rules

Commit .env.example with names and safe placeholders; never commit real secrets.
Load variables through the deployment platform, process manager, or an explicit local env-file mechanism. Node.js does not load arbitrary .env files merely because they exist.
Construct integrations during startup so missing or malformed variables fail before requests.
Keep auth secrets, API keys, database credentials, bearer tokens, and cookie passwords out of client variables, logs, error payloads, and telemetry.
Do not reuse an authentication secret or password as an Ownfold Recovery Kit secret, PRF result, device key, or root key.

The CLI-generated env.server.ts imports these Ownfold readers. It does not add T3 Env or a validator to the generated application’s dependencies.