# Custom domains

A package app normally lives on `*.kody.run`. A paid organization can also serve
its apps on a hostname it owns, such as `apps.example.com`. Kody uses Cloudflare
for SaaS to route the hostname and issue its certificate.

There are two kinds of binding:

- **App** (`binding_kind: "app"`): one internet-visible (public) app, served at
  the root of the hostname, for example `https://apps.example.com/`.
- **Org** (`binding_kind: "org"`): the organization's private apps, served at
  `https://apps.example.com/packages/{kodyId}`.

## Which hostnames are allowed

Use a hostname on a domain you control. Kody refuses these up front:

- Anything under Kody's own domains: `kody.codes`, `kody.run`, and any other
  domain Kody serves its app or package apps from. Package apps are never served
  there, so app code stays separate from Kody sign-in cookies.
- Anything under `workers.dev`.

The same rule decides both registration and serving, so a hostname that Kody
accepts is one it can serve.

A subdomain such as `apps.example.com` is the easiest choice. A root domain such
as `example.com` only works with a DNS provider that supports CNAME flattening
or ALIAS records.

## Set it up

1. **Add the hostname.** Call `packageAppCustomHostnameAdd` with `hostname`,
   `binding_kind`, and (for app bindings) `package_id`. Org admins can also use
   **Organization settings > Custom domains**. TXT certificate validation
   (`ssl_method: "txt"`) lets the certificate issue before traffic moves.
2. **Publish the DNS records.** The result includes `setup.records`, the exact
   records to add. Each one has a `type`, a full `name`, a `relative_name` (the
   name without your domain, which most provider forms want), and a `value`.
   Typically:

   | Type  | Name                                   | Value              | Purpose     |
   | ----- | -------------------------------------- | ------------------ | ----------- |
   | CNAME | `apps.example.com`                     | `domains.kody.run` | routing     |
   | TXT   | `_cf-custom-hostname.apps.example.com` | value from `setup` | ownership   |
   | TXT   | `_acme-challenge.apps.example.com`     | value from `setup` | certificate |

   Copy names and values from `setup.records`, not from this table.

3. **Turn the proxy off.** Every record must be **DNS only**. In Cloudflare DNS
   that is the grey cloud, not the orange one. A proxied record never validates,
   and the hostname stays pending.
4. **Wait.** Kody re-checks pending hostnames on its own: every few minutes for
   the first hour, then less often, for up to 48 hours. You do not need to call
   `packageAppCustomHostnameSync` in a loop. Most hostnames go active a few
   minutes after DNS is published. Call sync once if you want an immediate
   check; it returns the same `setup` block.
5. **Done.** When the hostname goes active, Kody emails the owners and the
   package's **Settings** page shows it as **Active**. The app serves on the
   hostname.

## Provider notes

- **Cloudflare:** set Proxy status to DNS only (grey cloud).
- **GoDaddy, Namecheap, Squarespace, Porkbun, and most registrars:** the Name
  field adds your domain for you. Enter `relative_name` (for example `apps` or
  `_cf-custom-hostname.apps`).
- **Route 53, Google Cloud DNS, and zone-file editors:** enter the full `name`.
- **CAA records:** if your domain has any, they must allow the certificate
  authorities Cloudflare uses.

## Status

`packageAppCustomHostnameList` (and add, sync, org settings, and the package's
Settings page) show a single `status` for each hostname:

- **Pending** (`pending`): Cloudflare has not found the records yet, or the
  certificate is still issuing. Kody keeps checking. The reason says what
  Cloudflare is waiting on.
- **Active** (`active`): the hostname and its certificate are both active, and
  the app is serving.
- **Needs attention** (`needs_attention`): a hostname that was never active did
  not go active in 48 hours, or Cloudflare reported a terminal problem first, so
  Kody stopped checking and emailed the owners. The reason says what to fix.
  After fixing DNS, sync once and Kody starts checking again. Some Cloudflare
  failures need the hostname removed and added again; the reason says when.

The raw Cloudflare fields (`hostname_status`, `ssl_status`) are still there for
debugging. A previously active hostname whose CNAME disappears gets a grace
period before Kody removes it.

Remove a hostname with `packageAppCustomHostnameDelete`.