Skip to content

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

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:

bash
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.

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 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.

boot log — an orphan row, and a reconcile that could not writetext
[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-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.

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 — a second service pointed at the same Postgresbash
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

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 covers the rest of the service setup, and One config, several sites is the developer-side view of the same feature.