> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinfoil.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom domains

> Configure and verify custom domains for your Tinfoil Containers.

## Default domain

Every Tinfoil Container gets a default URL based on its name and your organization's slug:

```
https://<container-name>.<org-slug>.containers.tinfoil.dev
```

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:

```
https://<container-name>.debug.<org-slug>.containers.tinfoil.dev
```

## 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](#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.

| Record | Purpose |
| - | - |
| CNAME on your domain | Routes traffic to Tinfoil |
| CNAME on `_acme-challenge.<your domain>` | Proves you own the domain, controls the **Verified** state, and lets Tinfoil issue and renew the TLS certificate for your domain |

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

| 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`) |

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

### Certificate CNAME record

| Field | Value |
| - | - |
| **Type** | CNAME |
| **Host / Name** | `_acme-challenge.<your domain>` (e.g. `_acme-challenge.api.example.com`) |
| **Target / Value** | The `acme-` target shown in the dashboard: the traffic target with an `acme-` prefix (e.g. `acme-a1b2c3d4e5f6.tf-dns.com`) |

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.

## Wildcard subdomains

Most domains don't need a wildcard. If clients connect only to `example.com`, including paths such as `/api`, the two records above are enough.

To serve subdomains such as `foo.example.com` and `bar.example.com` from one instance, enter `*.example.com` when you add the domain. Tinfoil registers `example.com`, which is the domain you select for the instance, and shows a third record:

| Field | Value |
| - | - |
| **Type** | CNAME |
| **Host / Name** | `*.<your domain>` (e.g. `*.example.com`) |
| **Target / Value** | The same hash target as the traffic CNAME |

Then set `shim.tls-wildcard: true` in your [routing configuration](https://docs.tinfoil.sh/containers/config-networking.md#routing), publish a release, and update the instance so its certificate covers the subdomains. The certificate CNAME also covers the wildcard certificate.

Tinfoil also shows the wildcard record for a domain whose instance sets `shim.tls-wildcard: true`. **Refresh** checks the record, and the dashboard warns about any instance using the domain that doesn't set `shim.tls-wildcard`.

Every subdomain reaches the same instance. To serve different instances, register a separate domain for each one. To add the wildcard record to a domain you already registered, add the domain again as `*.example.com`.

## Using the CLI

Register the domain, configure the two DNS records, and then verify it:

```bash theme={"dark"}
tinfoil domain add api.example.com
tinfoil domain verify api.example.com
tinfoil container create my-api \
  --repo myorg/my-api-config \
  --tag v1.0.0 \
  --custom-domain api.example.com
```

For a [wildcard domain](#wildcard-subdomains), quote the name so your shell does not expand it: `tinfoil domain add '*.example.com'`.

See [Managing containers from the CLI](https://docs.tinfoil.sh/containers/cli.md#custom-domains) 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:

```bash theme={"dark"}
# Check traffic CNAME record
dig @8.8.8.8 +short CNAME api.example.com

# Check certificate CNAME record
dig @8.8.8.8 +short CNAME _acme-challenge.api.example.com
```

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:

```bash theme={"dark"}
# macOS
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

# Linux (systemd-resolved)
sudo systemd-resolve --flush-caches
```

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:

```bash theme={"dark"}
# Find the authoritative nameserver
dig +short NS example.com

# Query it directly
dig @ns1.example.com +short CNAME _acme-challenge.api.example.com
```

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.