Custom domains

1. Prove you control the domain. Add one of these DNS records:

   • A CNAME from your domain to <vm>.turm.dev. This also routes traffic.
   • For an apex domain that can’t hold a CNAME: a TXT record at _agentcloud-challenge.<domain> with the value agentcloud-verify=<token>. domain add tells you the token. Point the domain’s A/AAAA records at the Turm edge.

2. Bind it to the VM.

   ssh turm.dev domain add demo www.example.com

3. Open it. The certificate is issued automatically on the first HTTPS request.

Manage domains with:

ssh turm.dev domain ls
ssh turm.dev domain rm www.example.com

Caution

When you delete a VM or run domain rm, also remove the CNAME. VM names are unique across Turm but can be reused: once demo is deleted, anyone can create a VM called demo, and a CNAME left at demo.turm.dev would point at it. Turm remembers who bound a hostname last. Your own account can bind it again with the CNAME; any other account needs the TXT record, which only someone who controls the DNS can add.

If domain add says another account bound the domain before (for example, you bought the domain), add the TXT record it prints. After that the domain is yours, and you can move it between your VMs with the CNAME alone.

Wildcard domains

A wildcard sends <vm>.example.com to your VM called <vm>, for every VM you have now or create later. You prove control of example.com once.

1. Claim it.

   ssh turm.dev domain add --wildcard example.com

   If the TXT record below is not in DNS yet, the claim is stored as pending and the output shows the record. A pending claim routes nothing.

2. Add the DNS records.

   • TXT at _agentcloud-challenge.example.com with the value agentcloud-verify=<token> from the output. Keep it: see the note below.
   • *.example.com pointing at the edge: a CNAME to turm.dev, or the edge’s A/AAAA records.

3. Verify.

   ssh turm.dev domain verify example.com

4. Open https://demo.example.com. The certificate for each name is issued on its first HTTPS request.

How names are matched:

• Only one label: demo.example.com routes to your VM demo. a.demo.example.com and example.com itself do not route (bind the apex with domain add <vm> example.com).
• Only your VMs. A name that is not one of your VMs gets a 404 and no certificate, even if another account has a VM of that name.
• A domain bound with domain add <vm> <domain> wins over the wildcard for that name.
• VM names are unique across Turm, so the label is your VM’s name as ls shows it.

ssh turm.dev domain ls                 # wildcards show as *.example.com, verified or pending
ssh turm.dev domain rm '*.example.com'

Caution

Keep the TXT record. While it is in DNS no one else can claim the domain. If it is removed, another account that adds its own TXT record can take the wildcard over. That is how a domain moves to a new owner.

Limits: 5 wildcard domains per account (pending ones count). Certificates for custom names share the edge’s issuance limits: 3 per name per week and 10 per hour for the whole edge, and a failed name is not retried for 10 minutes.