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.

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.

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 checks every few minutes. Make sure the A record’s value matches dns_target in the portal exactly. Use dig +short <your-host> to confirm.
  • 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.