Overview
When you add a custom domain to your Tinfoil organization, you need to verify
ownership by creating two DNS records: a CNAME record that points your domain
to Tinfoil’s infrastructure, and a TXT record that proves you control the
domain. Once both records are detected, your domain is marked as verified
and can be used for deploying containers under it.
Adding DNS Records
After adding a domain in the Tinfoil dashboard, you will see two DNS records
to create at your DNS provider.
CNAME Record
| Field | Value |
|---|
| Type | CNAME |
| Host / Name | Your custom domain (e.g. api.example.com) |
| Target / Value | The hash target shown in the dashboard (e.g. a1b2c3d4e5f6.tf-dns.com) |
TXT Record
| Field | Value |
|---|
| Type | TXT |
| Host / Name | _tinfoil.<your domain> (e.g. _tinfoil.api.example.com) |
| Value | The verification string shown in the dashboard (e.g. tf-domain-verify=api.example.com,a1b2c3d4) |
Verifying Your Domain
After creating both DNS records, return to the Tinfoil dashboard and click
the Refresh button on your domain. The system performs a live DNS lookup to
check for the expected records. If both are found, the domain status changes
to Verified. It usually takes a few minutes for DNS changes to take effect
so you may need to wait.
Troubleshooting
DNS Propagation Delays
DNS changes do not take effect instantly. CNAME and TXT records typically
propagate within a few minutes, but in some cases it can take up to 48 hours,
especially if you recently changed nameservers.
You can check whether your records have propagated by running these
commands in a terminal:
# Check TXT record
dig @8.8.8.8 +short TXT _tinfoil.api.example.com
# Check CNAME record
dig @8.8.8.8 +short CNAME api.example.com
api.example.com with your actual domain. Using @8.8.8.8
queries Google’s public DNS, which avoids stale results from
your local resolver cache.
Common Mistakes
Wrong TXT record host. The TXT record must be created on the _tinfoil
subdomain, not the root domain. For example, if your custom domain is api.example.com,
the TXT host should be _tinfoil.api.example.com, not api.example.com.
Missing the underscore prefix. The host must start with _tinfoil.
(including the leading underscore). Some DNS providers strip leading
underscores; double-check the saved record matches what you entered.
Cloudflare proxy enabled. If you use Cloudflare, make sure the CNAME record
has the proxy toggled off (DNS only / grey cloud). The orange-cloud proxy
rewrites the CNAME target, which prevents verification from succeeding.
Extra whitespace or quotes in TXT value. Some DNS providers add surrounding
quotes automatically. The TXT value should be exactly the string shown in the
dashboard, without extra quotes or whitespace.
Incorrect CNAME target. The CNAME must point to the exact *.tf-dns.com
address shown in the dashboard. Pointing to a different address or to an
IP will not work.
Stale Local DNS Cache
If dig @8.8.8.8 returns the correct records but the dashboard still shows the
domain as unverified, your local machine may have cached old results.
You can flush your local DNS cache:
# macOS
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
# Linux (systemd-resolved)
sudo systemd-resolve --flush-caches
Domain Still Not Verified
If your records have been live for more than an hour and verification still fails:
- Confirm you added the records to the correct DNS zone. If your domain is
managed by a different provider than your registrar, make sure you are editing
DNS at the active provider.
- Check for conflicting records. Some providers do not allow a CNAME at the
same level as other record types (CNAME flattening rules). If you have an
existing A or AAAA record on the same host, remove it or use a subdomain instead.
- Try querying an authoritative nameserver directly:
# Find the authoritative nameserver
dig +short NS example.com
# Query it directly
dig @ns1.example.com +short TXT _tinfoil.api.example.com
If you remove the TXT verification record after your domain is verified, the
domain may become unverified on the next check. Keep both DNS records in place
for as long as you use the domain with Tinfoil.
