# Custom Domains


You can point your own domain at your exe.dev VM.
TLS certificates are issued automatically.

Using a custom domain is a two-step process:

1. Set up DNS (CNAME or ALIAS) at your DNS provider, pointing your
   domain at `vmname.exe.xyz`. See below.
2. Register the domain with exe.dev:
   ```
   ssh exe.dev domain add <vm> <domain>
   ```
   exe.dev verifies the DNS resolves to your VM, then accepts traffic
   for that hostname. Until a domain is registered, requests for it
   are rejected with a `421 Misdirected Request` page. (See
   [Domain Allowlist Enforcement](#domain-allowlist-enforcement) below.)

List your domains with `ssh exe.dev domain ls <vm>` (one VM) or
`ssh exe.dev domain ls -a` (all your VMs). Remove with
`ssh exe.dev domain rm <vm> <domain>`.

## Check Your DNS

Enter your domain name and the VM name it should point to. We'll check
that the records resolve to that VM.

<div id="dns-checker"></div>

## Setting Up DNS

To point your domain at an exe.dev VM, edit the records in your domain's
DNS provider. (If you have not setup a DNS provider, your domain registrar
usually provides one.)

Which records you need to edit depend on whether it is a subdomain
e.g. `app.example.com` or an apex domain, e.g. `example.com`:

## Subdomains (CNAME)

For non-apex domains like `app.example.com`, create a CNAME record:

```
app.example.com  CNAME  vmname.exe.xyz
```

## Apex Domains (ALIAS + CNAME)

For apex domains like `example.com`, you need two DNS records.

1. **CNAME** record on `www` pointing to your VM:
   ```
   www.example.com  CNAME  vmname.exe.xyz
   ```

2. An **A** record on the apex pointing to the **IP** of `vmname.exe.xyz`. 
   However, many providers offer a convenient way to maintain this
   IP address dynamically, calling these types of records **ALIAS** or **ANAME**
   or **flattened CNAME**.
   ```
   # Lowest Common Denominator
   example.com  A  52.35.87.134
   # Cloudflare
   example.com  CNAME vmname.exe.xyz
   # Many others
   example.com  ALIAS vmname.exe.xyz
   ```

   The table below points you to the documentation for many common
   DNS providers.

   | Provider         | Mechanism | Documentation |
   | ---------------- | --------- | ------------- |
   | Cloudflare       | CNAME     | [docs](https://developers.cloudflare.com/dns/cname-flattening/) |
   | AWS Route 53     | ALIAS     | [docs](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-choosing-alias-non-alias.html) |
   | DNSimple         | ALIAS     | [docs](https://support.dnsimple.com/articles/alias-record/) |
   | Azure DNS        | ALIAS     | [docs](https://learn.microsoft.com/azure/dns/dns-alias) |
   | Google Cloud DNS | ALIAS     | [docs](https://cloud.google.com/dns/docs/records) |
   | Namecheap DNS    | ALIAS     | [docs](https://www.namecheap.com/support/knowledgebase/article.aspx/10128/2237/how-to-create-an-alias-record/) |
   | Porkbun DNS      | ALIAS     | [docs](https://kb.porkbun.com/article/68-how-to-edit-dns-records) |
   | DigitalOcean DNS | A         | [docs](https://docs.digitalocean.com/products/networking/dns/) |

## Cloudflare: Disable Proxy Mode or Configure Snippets

If you use Cloudflare for DNS, they tend to default you
to **Proxied** (orange cloud) rather than **DNS Only** (grey cloud).
Cloudflare's proxy replaces your desired CNAME/ALIAS targets
with Cloudflare IP addresses, and therefore breaks exe.dev's
custom domain support. To fix this, either disable their
proxy, or use Cloudflare Snippets (or Workers) to re-write
the request to point to `vmname.exe.xyz`. Snippets are a paid
feature.

## Wildcard domains

exe.dev is unable to generate TLS certificates for wildcard domains.
You must add an explicit CNAME entry for each custom name you want to support.
If you need an arbitrary list of custom names that point to a single
exe.dev VM, please [contact support](./getting-help).


## Domain Allowlist Enforcement

**NEW**: *This feature is enabled for new users, and we are
transitioning existing users to it.*

exe.dev only forwards requests for custom domains that you have
registered via `domain add`. Unregistered hostnames receive a
`421 Misdirected Request` page — even if the DNS points at your VM.
This prevents random hostnames from being routed to your VM and stops
attackers from issuing CNAMEs that funnel traffic at you.

To opt-in to the new behavior:

```
ssh exe.dev defaults write dev.exe domain-allowlist 2
```