Website and media domains

Different settings own different addresses. You can use only the selected subdomains for Typeroll while keeping the root website, email and unrelated subdomains on other services.

Scope	Setting	Example
Organization	Shared media host	media.example.com
Hosting Group	Site address base	sites.example.com or sites2.example.com
Site	Website host	www.customer.example
Site	Redirect hosts	customer.example → www.customer.example
Site	Optional media host	images.customer.example

A site address base is a parent for generated site and version addresses. It does not itself serve a website. Default’s base is configured in organization setup; additional groups have their own settings.

Publish once, then switch DNS

Core 0.2.116 / MCP 0.45.87 (pending release). This flow replaces main before changing DNS. Older installations prepare a separate branch and promote it at approval; update Core before following the single-publication flow.

Open Site settings → Publishing → Website and media addresses. The Move site to … card keeps the hosting account, zone, nameservers, edge certificate, permissions, publishing prerequisites, redirect capacity and candidate together. Saving an address is not a traffic switch. The card shows the current phase and only reports Live and verified after public checks succeed.

While a prepared switch waits for your DNS approval, it does not occupy the organization’s build engine. read_organization_build_engine lists it under awaiting_approval, not active_jobs, and other Sites may publish meanwhile.

1. Save the future website/media addresses. This only records intent: it does not rebuild, replace the current site or change DNS. Redirect-only changes retain the main artifact but require refreshed checks and renewed DNS approval.
2. If necessary, expand Add this domain to the hosting account. An organization owner/admin can create the zone, scan existing DNS, compare discovered records with current public answers and copy the reviewed inventory as DNS only. Existing conflicting records are never overwritten. Scanning is incomplete: check the old provider’s full inventory, including MX, SPF, every DKIM selector, DMARC and verification records. Do not confirm completeness if anything is missing; have your DNS administrator or agent supply missing records first. This import works only while the zone is pending. Typeroll then gives the exact nameservers to enter at your registrar; it never changes the registrar for you.
3. Shortly before changing DNS, select Publish for the new domain. It republishes the last published snapshot on main, replacing the current site immediately. The temporary/current hostname serves that same artifact. DNS is still unchanged. Later saved CMS edits stay unpublished. Compatible cached HTML may be reused for a pure origin change. Changes to the renderer, content, indexing policy, derived data or incompatible caches require fresh rendering. A cache-format upgrade needs one successful baseline build. New preparations freeze the installed renderer while retaining the published content. Resuming an existing job keeps its original renderer. Media checkpoints and content-addressed files remain reusable independently.
4. Select Review traffic switch, review the destination and interruption, then approve. For automatic DNS, Typeroll journals the prior records before writes and restores them if public verification fails or the agreed window expires (15 minutes in the UI; API/MCP allow 5–45 minutes). If another administrator changed the records afterward, restoration stops with an explicit conflict instead of overwriting their changes. The switch then ends as failed: review the previous records shown with the conflict, then prepare again. The new review reads the current DNS, and a record that already points at the site is not written again. DNS propagation can outlast rollback. Restore previous traffic uses the same journal; it restores DNS, not an older site artifact. External DNS must be changed and restored by its administrator or agent.

DNS approval reuses the same main publication, Git commit and deployed files. It does not push another branch, build again or upload again. Ordinary content publications while DNS is pending keep the new origins and replace that same main site. Review the latest receipt before approval; no new preparation is needed.

Absolute links and media URLs using a new hostname may not work until its DNS and certificate are ready. Choose this explicit publication shortly before the DNS switch. Old media aliases remain available; there is no separately served old version at the temporary hostname. Temporary media-transfer failures retain checkpoints and use bounded retries; invalid input and integrity failures do not.

An old preview-branch preparation cannot activate traffic under this flow. Choose Publish for the new domain once to replace main. After a DNS rollback, review and publish for the domain again; the previous DNS journal is not reused.

Agents use guide_publishing_domain_change (check, preview, save, prepare, approve, rollback) at POST /api/v1/sites/{siteId}/publishing/domain-guide. onboard_publishing_domain_zone uses the organization-scoped POST /api/v1/publishing/domain-onboarding endpoint for zone creation and reviewed DNS scans. Site-only credentials cannot administer organization zones. The existing domain tools remain available. prepare_publishing_domain_change now performs the explicit main publication, or refreshes setup when that publication already exists. confirm_rebuild is no longer needed to save future addresses. Traffic approval always needs an explicit human decision about the returned summary.

Redirect capacity

Cloudflare Pages accepts up to 2,000 static rules, 100 dynamic rules and 1,000 characters per rule. Wildcards and named placeholders count as dynamic. Generated trailing-slash variants and hostname aliases count too; the number of CMS redirect records is not necessarily the emitted rule count. The early source check conservatively counts every configured rule; final output removes rules that would shadow actual pages before checking the emitted file. Near the limit, remove obsolete shadowed rules from the CMS instead of relying on that filter.

Core 0.2.107 replaces Typeroll’s old 128 KiB _redirects transport limit with a bounded 10 MiB envelope and checks provider limits in dry-run and upload. Headers retain their separate 128 KiB bound. There is one _redirects file, not several. A representative 936-rule migration (837 static and 99 dynamic input rules) fits when its expanded static rules remain below 2,000. A dry-run checks source/export capacity; only a successful real build verifies the final static artifact. Do not remove an existing Bulk Redirect list until the replacement publication and its migration URL checks have passed and its removal is explicitly approved.

Set organization domains

Open Account → Publishing → Organization domains. With Cloudflare DNS access, choose a domain and enter the short Media subdomain and Sites subdomain labels. Review the complete addresses and select Configure domains. The refresh icon next to the domain list retrieves newly available zones.

For external or agent-managed DNS, expand Manual settings or external DNS, supply the full hostnames and follow the returned records. Check domain status reports the current result. Media migration and certificate checks can complete after settings have been saved; read each status before publishing.

R2’s shared media custom domain must belong to a Cloudflare zone in the same account as its bucket. Keeping authoritative DNS elsewhere requires a supported Cloudflare partial setup; selecting manual DNS does not remove that provider requirement. See external DNS requirements.

Add a Site’s website and media hosts

Open Site settings → Publishing → Website and media addresses. Enter the website host and optional media host. Choose the media path prefix: a separate media hostname can use an empty prefix, while sharing the website host can use /media.

Redirect hosts answer every request with a permanent redirect (301) to the website host and keep the path and query, for example https://www.example.com/about?ref=1 → https://example.com/about?ref=1. Enter them separated by commas.

Apex domains and www

A website host that is the domain itself, such as example.com, is an apex. Cloudflare Pages serves an apex only when the domain is an active Cloudflare zone in the Cloudflare account of the site’s Hosting Group, with Cloudflare’s nameservers at the registrar. A domain whose DNS stays at another provider can use a subdomain such as www.example.com as the website host instead.

A zone that you have just added is pending: Cloudflare has not yet seen its assigned nameservers at the registrar. A pending zone does not proxy records or get certificates, so neither the apex nor a redirect host in it can serve traffic. Change the nameservers at the registrar and wait until Cloudflare shows the zone as active. Records that point at your current host can stay DNS only meanwhile.

Typeroll checks the saved hosts against the zones it can read and shows blockers, such as a pending zone or an apex outside the hosting account, before you prepare a change.

A redirect host, typically www.example.com for an apex website, needs an active zone in a connected Cloudflare account and must be the zone apex or one level below it, which Cloudflare’s Universal SSL certificate covers. It does not serve pages. Cloudflare Pages cannot redirect by hostname, and customer sites have no server-side code, so a Single Redirect rule in the zone answers at Cloudflare’s edge. Its record becomes proxied with Cloudflare’s placeholder address 192.0.2.1. With automatic DNS, Typeroll creates the rule while the host still points at your current website, where the rule has no effect. Creating it needs the Cloudflare permission Dynamic URL Redirects (OAuth scopes dynamic-redirect.read and dynamic-redirect.write; for an API token, Zone → Single Redirect → Edit) on the connection whose account holds the zone. The Zone Transform Rules permission does not cover redirect rules.

When the installation requests Dynamic URL Redirects during onboarding, a new connection includes it and the rule is created automatically. A connection made earlier gets it with one Approve update on its Cloudflare card in Publishing. Without the permission, preparation returns redirect_rule_required and the domain panel shows the rule to add under Rules → Redirect Rules; its message also names the permission update when one is available. An agent can read the redirect_rules capability from diagnose_organization_cloudflare_connection before calling set_publishing_domains. A publication is live only after every redirect host answers 301 to the website host.

For MCP, set_publishing_domains.redirect_hosts is an optional array of up to four hostnames. approve_publishing_domain_cutover.accept_validation_window is an optional boolean; it is not blanket permission to interrupt traffic. Both are available in Core 0.2.87 / MCP 0.45.67. If a connector rejects them as unknown before making a request, compare its advertised schema with a fresh tools/list on the same portal endpoint (or describe_tool in compact mode). Start a fresh client conversation after refreshing the connector catalog. Do not bypass schema validation, change domain settings or reconnect Cloudflare merely to refresh MCP.

A media item’s public_path can retain an old path such as /wp-content/uploads/2024/photo.jpg; it must end in an extension that matches the file’s type. The next publication uses the selected active host and paths; saved future hosts take effect only through explicit domain preparation and cutover. Existing organization media links and previously published aliases remain usable; changing a preferred host does not invalidate them. Referenced media is included in static output, not committed as images to GitHub.

Before switching traffic

1. Save future hosts whenever convenient; keep editing and publishing normally.
2. Publish any intended CMS edits first. Publish for the new domain uses the last published snapshot, excluding newer unpublished edits, and retargets links, canonicals, sitemap URLs and media references with the installed renderer.
3. That publication replaces main at the current address. Check its indexing settings, DNS requirements and certificates; use Refresh domain setup if provider validation is still pending.
4. Review traffic switch, then Approve and switch traffic. With external DNS, your administrator or agent applies the reviewed records.
5. Typeroll verifies the real domain before reporting it live.

Normal publication remains available while DNS waits. It retains the new addresses and refreshes the main receipt. Read the latest receipt before approval; a stale approval is rejected. See publication destination.

A site set to noindex cannot launch by accident

You do not need sitewide_noindex while a site is built or migrated on its temporary address: Typeroll already blocks indexing there with X-Robots-Tag: noindex, and that block ends when the site moves to its own website host.

Once a website host is saved, the domain check reports the blocker candidate_noindex when search engines would still be told to skip the site: sitewide_noindex or sitewide_nofollow in Site settings, a robots noindex meta tag in scripts_head, or the same in the last publication or the prepared candidate. next_action is then resolve_noindex, and the migration launch check is not ready. Preparing and approving the change fail with HTTP 409 and candidate_noindex. The domain guide in Publishing offers both choices:

• Launch indexable (usual): Turn off noindex and publish for the new domain, or prepare with confirm_disable_noindex: true. This turns off sitewide_noindex and sitewide_nofollow in Site settings, removes noindex and nofollow from a robots meta tag in scripts_head (other directives stay), and builds the candidate indexable in the same step, with no separate publication. If the robots tag cannot be changed precisely, preparation stops with candidate_noindex_head; remove the tag in Site settings and publish first.
• Launch hidden on purpose: Keep it hidden on purpose, or prepare with allow_noindex_launch: true, for example for an intranet-like site. The choice is stored with the preparation, so approval accepts it without the flag.

Because the candidate rebuilds the last publication exactly, preparation stops with HTTP 409 and media_svg_unsanitized when that publication still contains an SVG stored before Typeroll sanitized SVG files (Core 0.2.113). Publish the site once at the current address, which stores and publishes a sanitized copy, then prepare the domain change again.

When a host already serves another website, Cloudflare Pages validates it only after its record points at Pages. Typeroll then asks you to accept a short validation window: the host does not answer until Cloudflare finishes, and Cloudflare does not document how long that takes. Typeroll never changes the record without that acceptance. See switch an apex from an existing host and the full domain-change procedure.

Use your own AI agent

The API and MCP return the same domain requirements as the UI. An agent with its own DNS-provider access can apply them, then request verification in Typeroll. Domain writes use a configuration revision to reject stale changes. Organization connections require an organization key; site domain writes require site admin permission. See the API and MCP mapping.

For sites still using the older managed publishing mode, use the separately labelled legacy managed-domain guide.

Different generators under one hostname

Domain settings select a website host, not which repository serves each path. For a CMS site with independently generated docs at /docs/, follow Different generators on one website. That separate hosting configuration must also be preserved during domain changes.

Previous website addresses

After an approved domain switch, Typeroll keeps the previous website addresses in previous_hosts. With access to the old address’s Cloudflare zone, it creates a Single Redirect that sends requests to the new website host with HTTP 301, preserving the path and query string. This does not consume one of the four optional redirect-host slots. The existing proxied Pages record and certificate remain attached; the rule does not replace their DNS records.

Old media paths are retained in the static publication, so a redirect to the same path on the new host continues to reach the file. Shared media hosts are not retired. An address that still serves the current media host is kept with noindex protection rather than redirecting its media to an unavailable destination.

The static artifact also adds a host-specific X-Robots-Tag: noindex, nofollow header to previous website addresses. If the connection cannot create a redirect, Typeroll checks that header on the actual deployed publication and shows a warning in Publishing and read_publishing_domains. If neither redirect nor noindex can be verified, the traffic switch does not complete silently. check_site_indexing reports previous addresses separately from the indexable production host.

Rollback removes only redirect rules created by that approved traffic switch, using its recorded before/after state. Existing customer rules and later edits are not overwritten. As with other domain rollbacks, this restores traffic, not an older artifact: publish for the restored address to restore its canonical and indexing policy too.

Sites switched before this behavior was introduced show unverified previous addresses. From Core 0.2.119, a normal publication installs the fallback headers and finishes missing redirects after the current website passes verification. It checks the old address’s active Pages certificate, connected zone and existing proxied CNAME, and records the exact rule write before submitting it. It never changes DNS or overwrites an existing rule. A permission or configuration problem keeps a verified noindex fallback with an actionable warning. A second domain build and traffic approval are not needed solely to finish legacy redirects. Verification-only retries remain read-only; saving domain settings or refreshing status never changes public traffic.

From Core 0.2.120, opening Publishing or checking the domain guide probes the previous addresses again. A warning captured before a redirect propagated can therefore become verified without another publication. A failed network check is reported as pending; it never changes DNS or redirect rules.

Check it

After the switch, poll_domain reports the domain as verified, check_site_indexing shows the expected robots policy for the new address, and the launch readiness report can compare the AI crawler setting with the domain’s Cloudflare zone. For a migration, run verify_migration_urls against the real domain as well.