Custom domains and DNS

Every service gets an auto-assigned hostname on the platform’s base domain. You can also attach your own domain. This guide covers both.

Related agent guides: Domain lifecycle (register / renew / transfer a domain over MCP) and Managing DNS records (raw zone editing). This page focuses on attaching a hostname to a service.

The auto-assigned hostname

When you create a service, Tandem assigns a wildcard hostname under the platform’s base domain — for the production cluster, launchtandem.com. The pattern is:

<service>-<project-slug>.launchtandem.com

The project slug is derived from your project: in platform.yml (lowercased, with non-alphanumerics replaced by -). Tandem also serves a wildcard TLS certificate for *.launchtandem.com, so HTTPS works immediately with no per-service cert provisioning.

This hostname is free, stable, and good for staging or for services that don’t need branded URLs. It’s what the portal links to in the service detail page.

Attaching your own domain

To use a custom domain (e.g. app.example.com):

  1. Go to the service in the portal and open Domains → Attach domain.
  2. Enter the full hostname you want to use.
  3. The portal records the domain in pending status and shows you the DNS target to point at.
  4. At your DNS provider, create an A record for that hostname pointing at the IP shown in the portal (for production, 143.198.106.97).
  5. Tandem’s verifier polls your DNS until the record resolves to the right target, then flips the domain to active and routes traffic.

The first request after activation triggers a TLS cert issuance via Let’s Encrypt (HTTP-01). Allow up to a minute for the cert to be installed.

Doing this over MCP

An agent attaches a domain with attach_domain (serviceId + hostname, needs manage + developer):

  • For a subdomain of an apex the org registered through Tandem, the A record is published automatically on Tandem’s authoritative nameservers and TLS issues within minutes — nothing to do at a DNS provider.
  • For an external hostname hosted elsewhere, the tool returns a DNS instructions block to relay to the user, then verification proceeds as above.

To register a brand-new domain instead of attaching one you own, use check_domain_availability → purchase_domain (which attaches the hostname it buys). To edit zone records directly — list_dns_records, create_dns_record, update_dns_record, delete_dns_record — see Managing DNS records.

Apex vs subdomain

Most DNS providers don’t allow CNAME records on the apex (example.com) — only on subdomains. If you want the apex on Tandem:

  • Use an A record at the apex pointing at the platform IP, or
  • Use a provider that supports ALIAS / ANAME flattening to a CNAME-style target.

Subdomains (app.example.com, www.example.com) can use either A or CNAME.

Redirects

When you attach a domain with a redirect_to_hostname set, Tandem serves a 301 to the target instead of proxying the service. This is how www.example.com → example.com and similar canonical-host redirects work.

What gets created

Attach action Database DNS Caddy
Auto-assigned platform hostname domains row (kind=platform) covered by the platform-wide wildcard route added on first deploy
Custom domain (external DNS) domains row (kind=custom, status=pending) you manage it at your provider route added when status flips to active

Verifying and troubleshooting

  • Domain stuck in pending — Tandem’s verifier rechecks automatically (every minute for fresh attaches, backing off with age) and activates the domain as soon as DNS resolves. Make sure the A record’s value matches dns_target in the portal exactly; dig +short <your-host> confirms what resolvers see. The portal’s Verify DNS button and the verify_domain MCP tool force an immediate recheck and report the resolved addresses.
  • TLS cert failed to issue — Let’s Encrypt requires the domain to actually resolve to us before issuing. Wait for verification to succeed first; the cert issuance retries automatically.
  • Want to remove a domain — use the Detach button in the portal. The route is removed and the domains row is deleted. Your DNS record at the provider stays untouched.

Internal architecture

Tandem runs its own authoritative DNS (PowerDNS) for the platform base domain and for customer zones that delegate to us. Most users don’t need this detail; if you do, ask a platform admin for the internal DNS architecture notes.