# Multi-site: the domain field and host-based resolution

URL: https://kywi-docs-production.up.railway.app/operating/multi-site-the-domain-field-and-host-based-resolution
Type: docPage

Kywi resolves a site from the request Host header, matched exactly against the domains in config, and config, not the database, owns that domain.

One process, one database, several hosts. Which site a request gets is decided by its **Host** header, matched by string equality against the `domain` and `domainAliases` each site declares in `kywi.config.ts`. There are no wildcards or subdomain matching — a host must appear in config verbatim (the port is ignored).

Confirm which site a host actually resolves to before debugging anything else. The AX surfaces resolve exactly like the rest of the API, so their first line names the site:

curl -s http://localhost:3000/llms.txt | head -1 # kywi-marketing-v3 curl -s -H 'Host: docs.localhost' http://localhost:3000/llms.txt | head -1 # Kywi Docs

## A host that matches nothing serves the first site

An unknown or malformed Host does not 404 and does not error — it falls through to `sites[0]`. So the failure shape of a misconfigured second host is not an outage; it is the first site's content appearing on the second site's domain, quietly, with a 200.

## A proxy must forward the visitor's Host, not replace it

Kywi deliberately ignores `X-Forwarded-Host`. If it honoured it, the API could resolve a different site than the page that called it. A reverse proxy, load balancer or CDN in front of Kywi must pass the visitor's Host header upstream unchanged — a proxy that replaces it with its own upstream hostname is the single most likely cause of one site serving another's content.

The Host header is client-controllable, but it can only *select* among sites you already declared, not grant access to one — see [Site-record public exposure](/operating/site-record-public-exposure-get-sites-is-unauthenticated/) for what an anonymous caller can learn about that list.

## Config owns the domain; the row follows

Site rows are reconciled from config on every boot and again in `kywi migrate`'s post-steps, matched **by slug** — the row's `slug` is the config site's `id`. Four columns belong to config: `name`, `domain`, `defaultLocale` and `theme`. They are diffed and written back whenever they disagree, which read the other way means an admin edit to any of the four is reverted at the next boot. Moving a site to a new domain is therefore a config change and a deploy, not a database update.

A configured site with no row gets one, plus a published home node, so its `/` renders immediately instead of 404ing until someone opens the admin. A row no config site claims is reported and left alone; Kywi never deletes a site.

[kywi] 1 site row(s) in kywi_sites match no config site: kywi-docs — left untouched; kywi never deletes a site. [kywi] could not reconcile config sites (permission denied for table kywi_sites). Continuing with the sites already in the database — a site declared in kywi.config.ts but missing a kywi_sites row will not resolve until this succeeds. Run `kywi migrate` to complete it.

## boot log — an orphan row, and a reconcile that could not write

Boot-time reconciliation is best-effort on purpose: a read-only database role logs that second line and the sites that do have rows keep serving. `kywi migrate` runs the identical reconcile with migration credentials, which is what converges a deploy whose app process cannot write — see [Running migrations against a live database](/operating/running-migrations-against-a-live-database/).

## Two rows, one domain, content in the wrong one

Reconciliation used to match rows by domain and slug them from the display name, so an install upgraded from that era can have a row slugged `kywi-docs` holding all the content while the new by-slug reconcile creates a fresh, empty `docs`. Kywi detects the shape and logs it — `created site "docs" and existing row "kywi-docs" both claim domain …, and no config site claims "kywi-docs"`. Either rename the old row's slug to match the config id and drop the empty one, or move the content across.

## A second host usually needs a second service first

Kywi resolves the host, but most PaaS edges route by Host too, so a second site stays unreachable until its real domain is attached at the platform. The fix is a second service on the same repo and database, given the platform's generated hostname and added to the site's `domainAliases` — a config-only edit, no row change.

railway add --service kywi-docs --repo <org>/<repo> --branch main \ --variables 'DATABASE_URL=${{Postgres.DATABASE_URL}}' \ --variables 'AUTH_SECRET=${{<primary-service>.AUTH_SECRET}}' \ --variables NODE_ENV=production railway domain --service kywi-docs # → kywi-docs-production.up.railway.app

## Railway — a second service pointed at the same Postgres

The second service doesn't share a volume: media uploaded through it lands on its own disk, invisible to the other service — keep uploads on the host that owns the storage. Once the real domain is attached to the primary service, the extra service is redundant and should be deleted; the alias can stay in config. [Deploying a host app](/operating/deploying-a-host-app/) covers the rest of the service setup, and [One config, several sites](/developing/one-config-several-sites/) is the developer-side view of the same feature.
