Configuration

Everything a krantho site can be told is a leaf of one typed tree. You write the leaves you care about in krantho.config.ts. A deployment overrides any of them from the environment. Everything else keeps its shipped default.

import { defineKranthoConfig } from '@krantho/config'

export default defineKranthoConfig({
  site: {
    domain: 'example.com',
    name: 'My Site',
    language: 'en',
    baseUrl: 'https://example.com',
  },
  auth: { mode: 'token' },        // the secret comes from KRANTHO_API_TOKEN
  llm: { provider: 'anthropic' }, // the key comes from KRANTHO_LLM_ANTHROPIC_API_KEY
  seo: { configDir: './krantho.seo' },
})

The object defineKranthoConfig() returns is what you hand to krantho where it is wired into your app, next to your collections:

import { createApiRouteHandlers } from '@krantho/server-next'
import config from '../../../krantho.config'
import { collections } from '../../../krantho.collections'

// The content API at /api/*: content, media, SEO, auth and the sitemap
export const { GET, POST, PUT, DELETE, PATCH } = createApiRouteHandlers({
  config,
  collections,
})

// The admin at /admin, in app/admin/[[...slug]]/route.ts:
//
//   import { createAdminRouteHandler } from '@krantho/server-next'
//   export const { GET } = createAdminRouteHandler()

import { createApiHandlers } from '@krantho/server-sveltekit'
import config from '../../../../krantho.config'
import { collections } from '../../../../krantho.collections'

// The content API at /api/*: content, media, SEO, auth and the sitemap
export const { GET, POST, PUT, DELETE, PATCH } = createApiHandlers({
  config,
  collections,
  // Editors preview drafts through a short-lived signed link
  sitePreview: 'signed-url',
})

// The admin at /admin, in src/routes/admin/[...path]/+server.ts:
//
//   import { createAdminHandler } from '@krantho/server-sveltekit'
//   export const { GET } = createAdminHandler()

import express from 'express'
import { createAdminServer, createHandler, toWebRequest, writeResponseHeaders } from '@krantho/server-node'
import config from './krantho.config'
import { collections } from './krantho.collections'

const api = createHandler({ config, collections, sitePreview: 'signed-url' })
const admin = createAdminServer(config)
const app = express()

async function send(res: express.Response, response: Response): Promise<void> {
  res.status(response.status)
  writeResponseHeaders(res, response)
  res.end(Buffer.from(await response.arrayBuffer()))
}

const owns = (prefix: string, path: string) => path === prefix || path.startsWith(`${prefix}/`)

// Mounted without a path: the handler routes on the full URL
app.use(async (req, res, next) => {
  if (owns('/api', req.path)) return send(res, await api.handle(await toWebRequest(req)))
  if (!owns('/admin', req.path)) return next()
  const url = new URL(`http://localhost${req.originalUrl}`)
  return send(res, admin({ url, cookie: req.headers.cookie }))
})

How a value is resolved#

One rule, applied once at startup:

defaults → krantho.config.ts → the environment.

The environment wins. Relative filesystem paths resolve against the working directory. Every problem found — a value that will not parse, a required field nobody set, a rule spanning two leaves — is collected and thrown as a single error naming each variable and path. A misconfigured deployment fails at boot with the whole list, not one item at a time:

Invalid krantho configuration:
  - KRANTHO_MEDIA_MAX_SIZE (media.maxFileSize): expected an integer, got "abc"
  - site.baseUrl: must be an absolute URL

Configuration versus wiring#

The split is what makes environment overrides mechanical.

Configuration is data — strings, numbers, booleans, lists, URLs. It lives in krantho.config.ts, and every scalar or list leaf has an environment variable. Structured leaves — the SEO archetype maps, the image presets and the webhooks — hold nested data and are set in code only.

Wiring is code that cannot be a string: collections from defineCollection(), page definitions, plugins, lifecycle hooks, a content change listener and how editors preview drafts (sitePreview). It stays an argument to the handler.

import { createApiRouteHandlers } from '@krantho/server-next'
import config from '../../../krantho.config'
import { collections } from '../../../krantho.collections'

export const { GET, POST, PUT, DELETE, PATCH } = createApiRouteHandlers({
  config,                                  // data
  collections,                             // wiring
  plugins: [],                             // wiring
  hooks: {},                               // wiring
  onContentChange: (change) => {},         // told about every committed write
})

Where media files are stored and how pages are cached are configuration as well: media.provider picks the file store, cache.pages the page cache, and their settings are leaves like any other.

The sections#

Every setting below lists each leaf with its environment variable, its type, its default and what it does.

Environment variables#

These leaves use established names instead of the mechanical form: KRANTHO_AUTH, KRANTHO_API_TOKEN, KRANTHO_JWT_SECRET, KRANTHO_TOKEN_ROLE, KRANTHO_TOKEN_EMAIL, KRANTHO_ADMIN_EMAILS, KRANTHO_SIGNUP, OIDC_ISSUER_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_REDIRECT_URI, OIDC_POST_LOGOUT_URI, KRANTHO_MEDIA_MAX_SIZE, KRANTHO_IMAGE_CACHE_MAX_ENTRIES, KRANTHO_IMAGE_CACHE_MAX_MB, KRANTHO_IMAGE_CACHE_TTI_SECS, KRANTHO_LLM_CLAUDE_CODE_OAUTH_TOKEN (llm.claudeCode.authToken) and CLAUDE_CONCURRENCY.

Every other leaf takes the mechanical form: split camelCase words, uppercase the path, replace the dots with underscores, prefix with KRANTHO_.

Types follow the leaf:

• Integers must parse as integers. KRANTHO_MEDIA_MAX_SIZE=abc fails the boot.
• Booleans accept true/false, 1/0, yes/no, on/off.
• Lists are comma-separated and trimmed: KRANTHO_SITE_SUPPORTED_LOCALES=en,nb,de.
• A variable set to an empty string counts as unset.

Secrets#

The secret leaves are auth.token.secret, auth.jwtSecret, auth.oidc.clientSecret, llm.anthropic.apiKey, llm.openai.apiKey, llm.gemini.apiKey, llm.openrouter.apiKey, llm.claudeCode.authToken, secrets.local.key, persistence.postgres.url, cache.cdn.gcp.accessToken, and the media store credentials media.vercelBlob.token, media.s3.secretAccessKey and media.gcs.credentials.

Each also accepts a _FILE suffix naming a file to read the value from. That is how a container platform mounts a secret without putting it in the process environment:

KRANTHO_LLM_ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic-key

The variable itself wins when both are set. Secrets are excluded from anything serialized to a browser by construction, and any dump of the tree replaces them with [redacted].

Language model settings at runtime#

The runtime reads the provider, model and base URL from the site settings store, not from the tree. On first boot the server seeds them into that store — only when the code passes an llm block, or the environment chooses a provider (KRANTHO_LLM_PROVIDER) and supplies that provider's key — and it never overwrites a stored provider. A key alone seeds nothing: a provider is on because it has a key, and the site uses the first one that is on when none was chosen. No credential is ever seeded or copied into the database: a key from the environment or the code stays where the deployment put it.

After that, Studio's Setup › AI provider wins for the provider, and for each provider's model and base URL. The credential is picked on every request, and every provider has one of its own. The claude-code provider uses KRANTHO_LLM_CLAUDE_CODE_OAUTH_TOKEN only, and refuses to run in production. Every other provider uses its own variable (KRANTHO_LLM_ANTHROPIC_API_KEY, KRANTHO_LLM_OPENAI_API_KEY, KRANTHO_LLM_GEMINI_API_KEY or KRANTHO_LLM_OPENROUTER_API_KEY) or the key the code passes, then the key pasted in Studio, and never another provider's credential — so a key rotated in the environment takes effect at once. Ollama needs none. krantho reads neither KRANTHO_LLM_API_KEY nor CLAUDE_CODE_OAUTH_TOKEN. See @krantho/ai. The build-time tools read the tree directly, so they always see the current value.

A key pasted in Studio is sealed before it reaches the database: AES-256-GCM under a key derived from secrets.local.key (KRANTHO_SECRETS_LOCAL_KEY) or, when that is unset, from auth.jwtSecret, either at least 32 characters. Only the running system can open it, so a database dump or backup reveals nothing. A site with neither refuses a pasted key and says so; set the provider's own variable instead. Rotating the key makes the stored keys unreadable, and they are entered again. Stored secrets are not part of any import or export.

Which settings a model takes differs by model, so llm.profiles sets them per model id over the defaults: reasoningEffort, reasoningHeadroom and temperature. See @krantho/ai.

Webhooks#

webhooks is a list of targets krantho POSTs to when content changes. Each takes an absolute http or https url, an events list with at least one of create, update, publish and delete, and an optional secret that signs the delivery with HMAC-SHA256 in the X-Webhook-Signature header (t=<timestamp>,v1=<signature>). A list of objects has no environment variable, so read the secret from the environment in krantho.config.ts:

export default defineKranthoConfig({
  // ...
  webhooks: [
    {
      url: 'https://hooks.example.com/rebuild',
      events: ['publish', 'delete'],
      secret: process.env.KRANTHO_WEBHOOK_SECRET,
    },
  ],
})

Each delivery is logged and shows in Setup › Integrations. A failed delivery is retried automatically, backing off from 30 seconds to an hour, up to five attempts; after that it stays failed until someone chooses Retry. The retry runs from the server's request handler, at most every 30 seconds and never in the way of a request, so a site with no traffic retries on its next visit. Deliveries are logged on SQLite and Postgres; on the filesystem adapter there is no log, so they are fire-and-forget and never retried. A webhook's secret is never serialized to a browser and is replaced by [redacted] in any dump of the tree.

Validation rules that span two leaves#

• site.defaultLocale must appear in site.supportedLocales.
• auth.mode: 'token' requires auth.token.secret.
• auth.mode: 'oidc' requires auth.oidc.issuer, clientId and redirectUri.
• auth.oidc.adminEntry: 'redirect' (with auth.mode: 'oidc') requires auth.jwtSecret.
• auth.session.sameSite: 'none' requires auth.session.secure: 'always'.
• persistence.provider: 'postgres' requires persistence.postgres.url.
• seo.enrichment.meta.minChars must not exceed seo.enrichment.meta.maxChars.
• cache.pages: 'cdn' requires cache.cdn.provider other than none.
• cache.cdn.provider: 'cloudfront' requires cache.cdn.cloudfront.distributionId.
• cache.cdn.provider: 'gcp' requires cache.cdn.gcp.project and cache.cdn.gcp.urlMap.
• A media.provider requires persistence.provider sqlite or postgres.
• media.provider: 'vercel-blob' requires media.vercelBlob.token.
• media.provider: 's3' requires media.s3.bucket and media.s3.region; a media.s3.endpoint requires media.s3.publicUrl; media.s3.accessKeyId and media.s3.secretAccessKey are set together or not at all.
• media.provider: 'gcs' requires media.gcs.bucket.

In production (NODE_ENV=production), the server also logs a warning at startup for auth.mode: 'none', and for any other mode without auth.jwtSecret. These are warnings, not errors.

Where the configuration is read#

Everything that reads the tree resolves the object defineKranthoConfig() returned against process.env: the API handler, the content loader, the page cache rules and the admin handler. Pass them the same object.

One process cannot see krantho.config.ts: the shared Next.js cache handler (cache.shared: 'database'), which Next.js loads by path. It opens the database from the defaults and the environment alone, reading only paths.* and persistence.*. If your database is not the default, set it by environment (KRANTHO_PERSISTENCE_PROVIDER, KRANTHO_PERSISTENCE_POSTGRES_URL, KRANTHO_PATHS_DATA_DIR). See Rendering and caching.

Loading a .env file in development#

Krantho does not read .env files itself — the process environment is the interface.

Next.js loads .env from the project directory into the environment before it reads next.config.ts, so next dev needs nothing more for a .env beside package.json. A file elsewhere, such as one shared by a monorepo, needs loading into the environment before next dev starts. Do not add Node's --env-file flag to it: next dev passes its Node flags to the server it starts through NODE_OPTIONS, and Node 26 refuses --env-file there.

Vite does not put .env into process.env for server code, so a SvelteKit or Express project lets Node load the file before the dev server starts:

{
  "scripts": {
    "dev": "node --env-file-if-exists=.env node_modules/vite/bin/vite.js dev"
  }
}

Every setting#

These tables are generated from the configuration schema by envReference() in @krantho/config. Secret marks a leaf that also accepts a _FILE variable; code only marks a structured leaf with no variable.

Site identity#

Paths#

Persistence#

Content engine#

Page cache#

Authentication#

Media and images#

Language model#

Stored secrets#

Admin assistant#

SEO#

Webhooks#

Build-time tools#