Custom domains

A Ferry project can use one shared hostname such as acme.feryl.io and one custom hostname such as go.acme.com.

Every hostname belongs exclusively to one project. That project controls its links, app association files, redirect destinations, and client-link policy.

Before you begin

• Custom domains require an active paid subscription.
• Use a concrete hostname such as go.acme.com.
• Wildcard hostnames are not supported.
• You need permission to change the hostname’s DNS records.

Connect the hostname

1. Open the project’s domain settings in Ferry.
2. Choose Add custom domain.
3. Enter the hostname without a scheme or path, for example go.acme.com.
4. Add every DNS record shown by Ferry.
5. Refresh the domain status after DNS has propagated.

The normal routing record points the custom hostname to:

customers.feryl.io

Ferry may also display a TXT validation record. Use the exact record name and value shown in the dashboard.

Domain status

Status	Meaning
Pending	Ferry is waiting for DNS or certificate validation
Active	The hostname is ready to serve links and platform association files
Error	The validation response needs attention

Do not ship the hostname in an app until it is active.

Configure the app

After activation, add the hostname to the platform configuration:

• iOS: applinks:go.acme.com in Associated Domains.
• Android: android:host="go.acme.com" in an autoVerify App Links filter.
• Expo: Add go.acme.com to the Ferry plugin’s linkDomains list.
• Flutter: Update both the iOS entitlement and Android manifest.

Ferry serves the Apple App Site Association and Digital Asset Links documents for active hostnames using the app identifiers stored on the project.

DNS guidance

• Do not proxy the hostname through another CDN in front of Ferry.
• Remove conflicting A, AAAA, and CNAME records for the same hostname.
• Keep the hostname separate from your website origin unless you intentionally move all traffic for that hostname to Ferry.
• DNS propagation and certificate issuance can take time even after the record is correct.

Verify the complete path

Create a test link on the custom hostname and check:

1. The link opens without a certificate warning.
2. An installed iOS app opens through a universal link.
3. An installed Android app opens without an app chooser.
4. A desktop browser reaches the project’s web fallback.
5. A device without the app reaches the correct store destination.

See troubleshooting when browser routing works but the operating system does not open the app.