Skip to main content

​
Default domain

Every Tinfoil Container gets a default URL based on its name and your organization’s slug:
For example, a container named api in an org with slug acme would be available at https://api.acme.containers.tinfoil.dev. Debug-mode containers use a separate domain:

​
Custom domains

Custom domains are included with every container subscription. Add a domain you control under Custom Domains in the Containers section of the dashboard, configure its DNS records, verify it, and then assign it to an instance.

​
Setting a custom domain

  1. Add and verify the domain (see Domain verification below)
  2. When creating or updating an instance, select it in the Custom Domain field

​
Validation rules

  • Must exactly match a domain your organization has verified
  • No protocol prefix (https:// is added automatically)
  • No path, wildcard, or port
  • Must not be in use by another instance in your org

​
Domain verification

Adding a custom domain requires two DNS records at your domain provider. The dashboard shows the exact values for each. The traffic CNAME check is reported separately and is not required for the domain to become verified, but an instance cannot serve traffic without it.

​
Traffic CNAME record

This record routes traffic for your domain to Tinfoil’s servers.

​
Certificate CNAME record

Certificates are issued inside the enclave at boot. The certificate authority proves control of your domain by looking up _acme-challenge.<your domain>; this record delegates that lookup to Tinfoil. The target is unique to your organization’s domain, so the same record also proves that you own the domain. Without it, the domain cannot be verified.

​
Completing verification

After creating the DNS records, return to the Tinfoil dashboard and click the Refresh button on your domain. The system performs a live DNS lookup for both records. The domain changes to Verified when the certificate CNAME points to its target, while the traffic CNAME result separately shows whether traffic routing is ready. It usually takes a few minutes for DNS changes to take effect so you may need to wait.

​
Using the CLI

Register the domain, configure the two DNS records, and then verify it:
See Managing containers from the CLI for listing and deleting domains.

​
Troubleshooting

​
DNS propagation delays

DNS changes do not take effect instantly. CNAME 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:
Replace 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 certificate CNAME host. The certificate CNAME must be created on the _acme-challenge subdomain of your custom domain. For example, if your custom domain is api.example.com, the host should be _acme-challenge.api.example.com, not _acme-challenge.example.com. Some DNS providers append the zone name automatically; if yours expects a relative name, enter the host relative to your DNS zone (for example, _acme-challenge.api in the example.com zone). Missing the underscore prefix. The host must start with _acme-challenge. (including the leading underscore). Some DNS providers strip leading underscores; double-check the saved record matches what you entered. Existing _acme-challenge records. A CNAME cannot share its name with other records. Remove any TXT or other records already on _acme-challenge.<your domain>, for example from a previous certificate provider, before adding the CNAME. Cloudflare proxy enabled. If you use Cloudflare, make sure both CNAME records have the proxy toggled off (DNS only / grey cloud). The orange-cloud proxy rewrites the CNAME target, which prevents the record from being reported ready. Incorrect CNAME target. Each 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. Existing _tinfoil TXT record. A verified domain with a _tinfoil TXT verification record stays verified while that record exists. Add the certificate CNAME before removing it; instances using the domain cannot obtain a certificate without the CNAME.

​
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:
After flushing, try the Refresh button again in the dashboard.

​
Domain still not verified

If your records have been live for more than an hour and verification still fails:
  1. 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.
  2. 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.
  3. Try querying an authoritative nameserver directly:
If you remove the certificate CNAME after your domain is verified, the domain can become unverified on the next check, and instances using it cannot obtain a certificate. Keep both records for as long as you use the domain with Tinfoil: the traffic CNAME for routing, and the _acme-challenge CNAME for verification and certificate issuance and renewal.