# The three deployment modes

URL: https://kywi-docs-production.up.railway.app/integrating/the-three-deployment-modes
Type: docPage

Three deployment modes differ only in which public-render files the scaffold emits — core never branches on `mode` at runtime.

`mode` is a required field on `kywi.config.ts`, and it is the scaffold's question, not the server's. It decides which files `create-kywi-app` writes into your project. Nothing in core reads it to decide how a request is handled.

export default defineKywiConfig({ // Deployment mode: // 'coupled' — this app renders the public site AND serves the API + admin. // 'headless' — API + admin only; no public rendering (GET / is 404). // 'decoupled' — API + admin here; a separate frontend consumes @kywi-software/sdk. mode: 'decoupled', // …

## kywi.config.ts

## What mode does not do

Core reads `config.mode` in exactly three places, and all three only hand the value back: the config-introspection JSON, the admin's runtime config, and the read-only **Deployment mode** row on the site settings screen. No route, no middleware, no render path branches on it. Editing the field in a running project changes one line of admin chrome and nothing else — in particular, flipping `headless` to `coupled` does not make anything render, because the files that would render it were never written.

## What it decided, once

Every mode gets the same admin catch-all, the same `app/api/v1/[...kywi]/route.ts`, the same middleware, the same layer registry, and the same four AX root routes (`llms.txt`, `llms-full.txt`, `sitemap.xml`, `robots.txt`). Coupled adds the public render path on top; headless and decoupled add one file that refuses to render.

coupled headless / decoupled ────────────────────────────────── ────────────────────────────────── app/(site)/layout.tsx app/page.tsx → notFound() app/(site)/[[...slug]]/page.tsx app/(site)/site.css components/site-nav.tsx scripts/sync-kywi-admin-css.mjs sites/<id>/themes/<theme>/index.tsx sites/<id>/themes/<theme>/index.tsx templates = { nav: SiteNav } templates = {}

The theme layer follows from the same branch: a non-coupled scaffold exports an empty `templates` map, because the nav template it would otherwise name lives in the coupled-only `components/site-nav.tsx`. A theme you write later against a headless project has no rendering host to hang templates on.

## Headless and decoupled emit the same project

The two non-coupled modes produce an identical file set; four of those files differ only by the mode string inside them. `kywi.config.ts` records it in the config object, `app/page.tsx`'s comment and not-found note name it, `AGENTS.md` states it in one sentence, and `README.md` does so twice — once in its opening description, and again in a **Separate frontend** heading that decoupled alone gets, with a `createKywiSdk` snippet pointed at `/api/v1`. The distinction is a statement of intent for whoever reads the repo next — headless means nothing is planned to consume it as a site, decoupled means something is. Choose either and you can change your mind by editing prose.

## The admin and the API are identical in all three

`/admin` is the whole core admin in every mode, and every `/api/v1` route is registered in every mode. A headless install is not a reduced install; it is the same install with no public HTML.

## Changing the field later

`create-kywi-app upgrade` works out which mode a project is by regex over `kywi.config.ts` — it looks for a quoted `coupled`, `headless` or `decoupled` after `mode:`. When it matches nothing it assumes coupled and says so, then regenerates the layer files on that assumption. So the field is worth keeping literal and on one line: a value assembled from a variable or an env lookup reads as absent, and your headless project gets upgraded as if it rendered pages.

Switching modes for real is a file operation, not a config edit. Going coupled means adding the five render-path files and re-pointing the theme layer's `templates`; going headless means deleting `app/(site)` and `components/site-nav.tsx` and adding the 404 home page. See [What the scaffold generates](/developing/what-the-scaffold-generates--and-what-it-deliberately-doesnt/) for what each of those files is, and [Rendering a page in coupled mode](/developing/rendering-a-page-in-coupled-mode/) for what the coupled path actually does.

## Which mode you want

The choice is about where HTML is produced, and it constrains less than it looks like it does — but the one thing it cannot buy you is a browser-side integration. A separate frontend consumes the API from its *server*: see [Topologies that work — and the cross-origin wall](/integrating/topologies-that-work--and-the-cross-origin-wall/) before you design around a decoupled deployment, and [Coupled, headless, decoupled](/start/coupled--headless--decoupled/) for the version of this decision you make before scaffolding.
