Connect a custom domain

An app owner can connect one exact domain in App Settings → Domains when the installation enables custom domains. Both example.com and app.example.com are supported. www.example.com is a separate hostname; adding the apex does not also add www or other subdomains.

Domain settings belong to the app, outside opencloud.yaml. Code deployment or rollback does not claim, move, or remove a domain. The same active release, routes, visibility, and app access rules serve both addresses.

Set up DNS

1. Enter the domain name without https://, a path, or a port. Domain changes require the confirmed app owner.
2. Copy the exact ownership TXT name and value shown in Domains. Ownership verification is required even when traffic already points to OpenCloud.
3. Point web traffic to the shared target shown by the installation. For a subdomain, use the traffic CNAME. For an apex, use your provider's ALIAS, ANAME, or CNAME flattening. If the installation publishes A/AAAA alternatives, use those when your provider lacks flattening; do not invent an origin IP or copy the address of an unrelated app.
4. Keep existing MX, mail TXT, NS, and unrelated DNS records. Replace only the relevant web traffic records. Follow any concrete mail-dependency notice shown for your domain.
5. Copy the certificate-validation CNAME when it is marked required. Some installations require this delegation before issuing a certificate. Keep this record DNS-only: in Cloudflare, turn proxying off for the certificate CNAME. Use the exact generated name and target shown in Domains. When the record is marked optional, it remains an optional way to delegate origin certificate issuance and renewal.
6. Add all required records for your chosen web traffic option, then choose Check connection. DNS updates may take time; the screen reports the results without starting checks merely because it is opened or refreshed.

Cloudflare proxying can remain enabled from the start. Apex CNAME flattening is supported for web traffic; the separate certificate CNAME stays DNS-only. OpenCloud does not need your Cloudflare login or API token. Setup depends on the observed ownership, public HTTPS, origin HTTPS, and app connection checks. A browser padlock alone does not establish readiness. If a check fails, use its reported DNS, TLS, or traffic-target detail to fix the relevant configuration and check again.

If certificate setup is pending because delegation is missing or incorrect, add or correct the required certificate CNAME and check again. If certificate DNS is temporarily unavailable, keep the record in place and retry the check later. Ownership TXT verification remains a separate requirement. The domain does not become connected merely because one of these checks succeeds.

When the domain connects

While setup is pending, the OpenCloud address remains primary. Once all required checks succeed, Open custom domain appears and the custom domain becomes the primary browser address. Ordinary navigation to the OpenCloud address uses a temporary redirect that preserves the path and query. Service requests, development previews, and release verification keep their dedicated platform behavior. The Domains screen retains the OpenCloud address separately, and the dashboard stays on the platform domain.

Private apps still require login. Public apps can still use signed-in features. Use the normal OpenCloud SDK and central sign-in flow; do not build a custom-domain login form or copy sessions between origins. The custom domain automatically continues in the same tab to auth.<base-domain> and returns through a one-time callback after access is established. For email-link sign-in, the email window approves the request and tells the person to close it; the initiating Auth tab completes sign-in and returns to the app. Confirmed browser sessions retain their fixed 30-day lifetime and normal current-browser sign-out behavior.

The SDK does not expose auth.signOut(). A custom-domain app's explicit sign-out action posts to its same-origin endpoint and reloads to clear the SDK's in-memory session and connections:

const response = await fetch("/_opencloud/sign-out", {
  method: "POST",
  credentials: "same-origin",
});
if (response.ok) location.reload();

This revokes that browser's parent session and its custom-domain aliases; other devices remain signed in. Keep this action behind a visible Sign out control, and show an error if the request fails.

Browser permissions and local browser storage belong to an origin. A Web Push subscription on the OpenCloud address is not a subscription on the custom domain: offer Subscribe from a user gesture on the new address. Removing or replacing a domain invalidates its old connection authority. Continue to use the SDK for Data, Files, Functions, Realtime, and notifications; do not construct platform URLs or copy cookies or bearer credentials into app code. Existing Realtime sockets use bounded access rechecks and can reconnect during normal session refresh; see Realtime. Long-running Functions have a separate Data authorization limit.

A website domain does not change your email sender or inbox. Existing OpenCloud-managed email addresses continue to work. Sending or receiving as support@example.com is a separate capability and is not enabled by this domain connection.

Remove or replace it

Choose Remove domain and confirm. The hostname disconnects and the app retains its OpenCloud address. Cleanup may continue afterward. You can add a different hostname immediately; reusing the removed hostname must wait until its certificate cleanup finishes. Remove stale web traffic and ownership records at your DNS provider when you no longer need them.

Full hosted MCP exposes get_app_domain, add_app_domain, check_app_domain, and remove_app_domain. Mutation tools require an explicit idempotencyKey of 8–200 characters; reuse the same key and input after an uncertain result. For example, add_app_domain accepts:

{
  "appId": "6f9619ff-8b86-4e6e-a62a-889950f42d3e",
  "body": { "hostname": "app.example.com" },
  "idempotencyKey": "domain-add-example-1"
}

Check and remove use appId and their own idempotencyKey, without body. Choose a new key for a different intended effect or changed input. The focused /build surface does not manage domain ownership. Public CLI 3.9.0 provides the equivalent opencloud app domain get|add|check|remove commands; App Settings and full MCP remain supported alternatives.