# Custom domains & HTTPS

> Custom domains, HTTPS, and DNS.

[HTML version](https://snoozestack.com/docs/domains/) · [Docs index](https://snoozestack.com/llms.txt)

Connect a domain you own to a project — declared in `project.toml`, claimed with one command — and snoozestack manages everything behind it: the hosted zone, a free certificate, the DNS records, and the edge distribution that puts the domain in front of the project's websites and API. The console's **Sites → Domains** page shows the same checklist and records.

**Why use it**

A custom domain is mostly about not being locked to someone else's hostname. The name your users bookmark, the origin your mobile app has pinned in a shipped binary, and the address in your OAuth provider's config are all expensive to change later — putting them on a domain you control means the backend behind them can move without any of it breaking.

There is also a concrete unblocking effect. Some things only your own name can do: Google's consent screen says “to continue to” the domain the login runs on, Apple's universal links need a verification file served from your domain, and cookies scoped to your own name are what let a site and its API share a session.

The domain itself stays yours — registered wherever you registered it. SnoozeStack only runs the serving infrastructure behind it, so disconnecting a domain from a project leaves the domain itself untouched.

- **Your site on your own name** — `example.com` serving your published website, and `example.com/sites/<name>/` serving the others.
- **One build, either URL** — A connected domain serves the same `/api` paths as `<ref>.snzzz.com`, so a browser app that calls `/api/functions/v1/…` on its own origin works from both without a rebuild or an environment variable.
- **Environment-per-subdomain** — `staging.example.com` and `app.example.com` on separate projects, sharing one zone and one wildcard certificate.
- **Email and verification records** — Once the zone is here, the TXT/MX records for your mail provider and any domain-verification tokens are managed on this page too.

| Surface | Availability |
| --- | --- |
| Portal UI | The setup checklist with live progress, zone/NS/certificate status, and DNS record management |
| CLI | `snoozestack domains claim/status/list/delete/primary/retry` and `domains records …` |
| SDK / HTTP | None — script it via the Management API's domains/records endpoints instead |

### Connecting a domain

```bash title="snoozestack/project.toml + terminal"
[[domains]]
name = "example.com"
```

```bash title="terminal"
snoozestack domains claim example.com     # idempotent — re-running reports status
snoozestack domains status                # the checklist, incl. the NS servers to set
```

One domain per project, since the certificate covers the apex and its subdomains. Claiming is deliberately its own step rather than part of `snoozestack publish` — the infrastructure work is asynchronous and can take minutes to hours, so publish only validates the declaration and reports drift, never claims or disconnects. snoozestack finds or creates the public hosted zone and requests a certificate for `example.com` + `*.example.com`, inserting the DNS validation records into the zone automatically. That takes a few seconds, and then the page shows the zone's **name servers**.

A name already connected somewhere else on snoozestack is refused, and so is one whose zone here belongs to another organization — a domain can only be claimed once, in either direction between an apex and its subdomains. Projects in the same organization are the exception: they share the zone, and it is torn down when the last of them disconnects.

The certificate then sits at `pending validation` until you do your part: **set those name servers as the domain's NS entries at your registrar**. Validation runs through this zone, so the certificate can't issue while your registrar still points somewhere else — this is the one step nothing on the snoozestack side can do for you. Once the delegation is live the certificate issues by itself, usually within minutes, and the page updates on its own.

### What the domain serves

The apex is set up for you as soon as the certificate issues, and it serves everything the project host does — the same paths, in the same shapes, from one edge distribution:

- **`example.com/` — your primary website**. Whichever site is marked primary on the [Websites](https://snoozestack.com/docs/websites.md) page is served at the apex; make a different one primary and the apex follows it, without the domain going down in between. The edge reads the site's published files directly (the portal is not in the serving path) with the same semantics as the project URL: `index.html` for directory URLs, trailing-slash redirects, assets cached at the edge.
- **`example.com/sites/<name>/` — your other websites**, at the same paths they already have on the project host.
- **`example.com/api/…` — the project API**, the same `/api/auth`, `/api/functions/v1`, `/api/storage/v1` and `/api/webhooks/…` the project host answers. A published browser app calling `/api` on its own origin therefore works on both, with nothing to rebuild.

Nothing moves off `<ref>.snzzz.com` to make that happen. Both URLs stay live for as long as the domain is connected, which is what makes the choice below instant and reversible. Three things stay on the project host permanently and by design: a server-side function's own `SNOOZESTACK_URL`, the OAuth provider callback you registered at Google or Apple, and the hosted `/auth/reset` and `/auth/confirm` pages — none should depend on a DNS change you might make later, and a verify link already sitting in an inbox has to keep arriving somewhere.

The **preferred origin** (`snoozestack domains primary platform|custom`, or the switch next to the domain name in the console) chooses which of the two URLs snoozestack *hands out*: copy buttons, site and function URLs, webhook URLs, SDK snippets. It stays on for the whole of a connect — asking for a domain is asking to be served at it — and the cutover happens as the last step of the setup, once every route has been requested on the domain and answered. Until then the project URL keeps being handed out, and while setup is running the switch is locked: **Disconnect** is how you change your mind, not the switch. There is no DNS to wait on, so it takes effect at once and can be flipped back just as fast. It never takes either URL down; links you have already shared keep working whichever way it is set. Only **Disconnect** gives the domain up.

Auth emails and redirects follow the preferred origin too, and both of the project's own origins stay on the [redirect allowlist](https://snoozestack.com/docs/authentication.md) either way, so links already sitting in an inbox keep working.

Turning it *on* also re-runs the setup checks, and the checklist goes live again while they do: the edge routing is compared against what the project should have and rebuilt if it has drifted, DNS is re-checked, and every route is requested to confirm it answers. That is the point at which your project starts depending on the domain, so it is the right moment to prove the domain still works rather than trust a connection that finished weeks ago. A rebuild takes the few minutes the edge needs to deploy; the domain keeps serving throughout, and if a check fails the step says which route and offers a retry.

The distribution follows a pay-as-you-go setup — SNI certificates, no WAF, no Origin Shield, nothing with a fixed monthly cost. Disconnecting tears it down: the alias comes off and the distribution is disabled immediately, then deleted once the edge finishes deploying the disabled state, which is the few minutes the last step of the disconnect waits on.

### DNS records

The zone's records are listed inline, and you can add or delete `A`/`AAAA`/`CNAME`/`TXT`/`MX`/`SRV` records — e.g. the TXT and MX entries for your mail provider. The zone's SOA/NS records and the edge alias records are managed for you.

Disconnecting a domain moves generated links back to the project URL and checks it is healthy before removing anything, then releases the edge alias, deletes the records snoozestack owns, tears the distribution down and deletes the hosted zone with all of its records — so keep a copy of any records you added yourself. It runs to completion whether or not you stay on the page. The certificate stays in your account, and reconnecting later creates a fresh zone with new nameservers to set at your registrar. If you only want snoozestack to stop handing the domain out, turn the switch off instead — that leaves everything serving.