Kernlift

Configure a working project

Set startup variables, make sign-in and email work, then connect and verify the providers your product uses.

For a new deployment, first make sure the app starts, an administrator can sign in, and verification email is delivered. Enable payments, files, AI and other integrations only when your product needs them. A page being present does not mean its provider is ready.

Before you begin

  • Migrate the database, obtain access to the runtime environment, and sign in as an administrator. If no administrator exists, follow Start the admin console.
  • Have test or sandbox accounts for the providers you intend to use. Provider credentials belong in the admin console, not .env. See Environment variables for the startup list.

1. Set the startup environment

Use .env.example as a checklist. Set APP_ENV, BETTER_AUTH_SECRET, SITE_URL and the database connection in local .env or your hosting platform. In production, generate a fresh BETTER_AUTH_SECRET; do not use the template value:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

In production, also set CONFIG_ENCRYPTION_KEY to a value of at least 32 characters, generated the same way, so the provider credentials you enter next are encrypted in the database. Keep it stable once set. If credentials were saved before you set it, run pnpm db:encrypt-config-secrets once. See Encrypt stored credentials.

Restart the app after changing environment variables, then run pnpm db:migrate and confirm the migrations complete. See Runtimes and database adapters for dialects and Workers bindings.

2. Keep a working sign-in method

Open Auth Config in the admin console. Email/password sign-in is enabled by default. If you turn it off, configure and test Google or GitHub first so users retain a way to sign in. Set verification, sign-up and account-deletion policies as needed. For social sign-in, register the callback URL shown by the page with the provider before saving its client ID and secret.

Sign out and test sign-in and new-account registration. See Email/password sign-in and Social sign-in for fields and callback steps. The session-signing BETTER_AUTH_SECRET is an environment variable and does not appear on this page.

3. Deliver a real email

In Email Config, select Resend, Cloudflare or Aliyun, enter credentials and a verified sender, enable the provider and save. Complete sender-domain verification at the provider first. Then use Email → Test send and confirm success in delivery history. Test registration verification or password reset as well.

A successful save confirms that the settings were stored. It does not confirm that mail was delivered. If delivery fails, check the sender domain, credential and provider error in the delivery record. See Email for fields and templates.

4. Enable only the capabilities you use

Configure each integration when needed, and complete its end-to-end check before moving on:

CapabilityConfigureConfirm
Checkout and subscriptionsEnter sandbox credentials, return URLs and webhook secret in Payment Config; create at least one active plan in Plans (/admin/plans)Complete a sandbox checkout. An order changes state only after a signed webhook or server-side provider confirmation. See Payment providers
Uploads or Agent artifactsChoose S3-compatible storage or an R2 binding; set the bucket, credentials, size and content-type limitsUpload an allowed file and download it as its owner. See Storage
AI tasks or Agent modelsCreate a channel and provider scene; set credentials, model, scene route and pricingRun a test task, confirm a real provider result and recorded usage. See AI providers and Scenes
Analytics and support chatSet script IDs; add a server-side access token if reports are neededConfirm the script loads and records a test event; check report pulling separately. See Analytics
Agent sandbox and web researchInstall agent-starter; configure object storage and AI before sandbox, SearXNG and crawl4ai connections and limitsTest search and crawl separately, then run a workbench task using those tools. See Agent starter

Caching works with its defaults. If you need to change it, use Cache Config to set enablement, TTL and an available backend per domain. Turn off Enabled to bypass a cache; a zero TTL is not accepted. See Cache. Newsletter, notifications, pricing plans and API-key rate limits have their own business pages; see Run the admin console for where each one lives.

Confirm readiness

Open /setup. Session secret, sign-in method, email delivery and scheduled jobs are required; the page also reports optional payment, storage, AI, newsletter and analytics readiness, and Credential encryption, which becomes required when stored credentials cannot be decrypted. It does not check cache, Agent sandbox or search, so complete the functional tests above. Do not infer provider readiness from whether a page opens.

Troubleshoot

  • The app will not start or rejects the session secret: Check APP_ENV and BETTER_AUTH_SECRET, then restart. Production rejects an empty or template secret.
  • A setting saved, but the capability is not ready: Check the page's status and test result, then inspect the provider error. Saving and connecting are separate checks.
  • AI Config appears in the menu but will not load: The sidebar uses config.read, while the page requires ai.read; saving requires ai.write.
  • A module's pages or menu entries are gone: Check Plugins (/admin/plugins); a disabled plugin hides its entries and its pages return not found.
  • /setup reports that scheduled jobs are not running: Fix this on the deployment platform. See Troubleshoot a project.
  • A change seems stale: Console saves usually clear their cache domain. A direct database edit may need a TTL expiry or manual clear. See Cache.