Custom domains

The Custom domains page (labelled ACM — automated certificate management) is where your own hostnames meet your gateways. It's a single apex-grouped list — every hostname nests under its apex (app.example.com and staging.example.com both sit under example.com), split across Personal and Team tabs. A group is either verified (the apex is in your wildcard pool, so a *.example.com cert covers every subdomain) or synthetic (subdomains exist but the apex was never verified, each carrying its own per-host cert). Custom domains require a paid plan; wildcard apexes require Pro or Team.

The console owns DNS verification and certificates end to end — you never handle certificate files. Every certificate is issued via DNS-01: you add one CNAME record at your DNS provider, the console proves control and issues, and the relays serve the certificate for you.

A team gateway's custom domains and verified apexes come out of the team's own pool, separate from your personal one — the Team tab shows them.

The CNAME recipe

Whenever a certificate needs DNS proof, the console shows a Setup recipe with two copy fields:

• the CNAME record name — a _acme-challenge… name under your domain,
• the target — a verification hostname the console controls.

Add that record at your DNS provider, then press Verify on the row. Issuance takes about a minute after DNS propagates. Leave the record in place — it is reused for renewals.

Each row carries a TLS badge showing the certificate lifecycle: DNS setup needed (record not verified yet) → verifying… → TLS ✓ (issued; hover for the expiry date). failed means the last attempt did not complete — fix the DNS record and press Verify again.

Verified apexes — the wildcard pool

Verifying every hostname separately gets old. Instead, verify an apex once: add the one CNAME record and Verify on its group header (a synthetic group offers Verify apex to upgrade it in place). That issues a *.example.com wildcard certificate — and from then on, any subdomain (app.example.com, staging.example.com, …) attaches instantly, with no DNS step at all.

How many domains and apexes you can hold are hard caps per plan tier — for every tier, Team included: at the cap the next add is refused (a tenant already over a lowered cap keeps what it has, but can't add more). The apex count (N / M apex domains on Personal, a plain count on Team) sits at the top of the list.

One refusal is deliberate and not about caps: you cannot attach a subdomain of an apex that another tenant has verified. If your team needs hostnames under an apex you verified personally (or vice versa), the supported path is sharing the apex into the team (the Share action below) so its gateways reuse the wildcard — not re-attaching pieces of it across tenants. A verified apex group's header carries these actions:

• Setup — reveal the apex's CNAME recipe again.
• Move… — transfer the apex to another tenant you manage: your Personal account, or a team you own/manage. One-way (the destination must be under its own apex cap), and it takes the wildcard cert with it.
• Share — the chip (showing a tenant count, or "Share" when unshared) opens a panel to share the apex into other teams you administer, so a team gateway can reuse the wildcard without re-verifying. Many-to-many; each shared tenant sees the apex read-only. A shared apex shows on both the owner's and the sharee's tabs.
• Resync — push the apex's already-issued certs and routes out to the current relay set right now (including bridge-reachable edges). Useful after you add a relay or edge that should start serving the domain.
• Remove — release the apex. Blocked while subdomains still use its wildcard certificate; the warning lists which hostnames to detach first.

Subdomain rows — per hostname

Each group's rows are its attached hostnames, showing the gateway and service each points at plus, underneath, a chip per synced relay currently serving that hostname (an edge-kind relay is tagged as such — this is how you confirm the domain is riding your own edge rather than the shared fleet). Each row's readiness comes from its own certificate — a subdomain attached before its apex was verified keeps its per-host cert; a ready (via *.apex) badge is cosmetic, never a substitute for the row's own cert.

+ Add custom domain (page header) or + Add subdomain (on a group) asks for:

• Gateway — which gateway serves it (pre-filled when you open the dialog from a target row).
• Hostname — e.g. app.example.com.
• Service — the target name on that gateway.
• Certificate — if the hostname's apex is already in your wildcard pool, you can reuse the wildcard (instant, no DNS step) or issue a fresh per-host certificate (one DNS round-trip). The wildcard is the default when available.
• Relay — Auto serves the domain on every relay the gateway connects through; or pin it to one specific relay (say, your own edge relay so the traffic never touches the shared fleet).

If a certificate for the hostname was already issued, the domain is live immediately ("TLS already active ✓"); otherwise you get the CNAME recipe and a Verify button.

Detach removes a hostname — it stops serving immediately. The certificate is kept, so re-attaching the same hostname later (or moving it to another target) does not repeat the DNS dance.

Where domains attach

This page is the domain inventory; the binding lives on targets. Each target row on a gateway's detail page shows its attached domains and is where you assign, move, make public, or detach them — including the auto-assigned random *.burrowee.net names, which need no setup at all. (A random name you release goes back toward the shared pool — after a quiet period it may be claimed by someone else, so don't count on getting the same one back.)

Two bindings beyond the ordinary web target:

• Raw (TCP) targets take custom domains like any other target, but random domains never apply to them — they are reached at <service>.<relay-domain> instead. See Gateways → the targets table.
• Gateway alias domains attach a custom domain to a gateway itself rather than to one target, from the Alias domains panel on the gateway detail page — a distinct kind of attachment with its own add / DNS-verify / remove flow.