Custom Domains

TSDProxy can serve your containers on custom domains instead of the default <name>.<tailnet>.ts.net. A pluggable DNS + TLS system manages CNAME records and certificates automatically.

Overview

Without custom domains, every proxy is reachable at https://<name>.<tailnet>.ts.net. With custom domains enabled, a proxy can be reached at any domain you own (e.g. app.example.com).

TSDProxy handles the full lifecycle:

1. Creates a DNS CNAME pointing your domain to the Tailscale machine
2. Provisions a TLS certificate for the domain
3. Serves HTTPS traffic on the custom domain
4. Cleans up DNS records when the proxy stops (configurable)

The dashboard shows DNS and TLS status badges (pending, active, error) for proxies with custom domains, so you can monitor the setup progress in real time.

How it works

Container with tsdproxy.domain label
        |
        v
  DNS Provider (Cloudflare / MagicDNS)
    - Creates CNAME: app.example.com -> myapp.tailnet.ts.net
    - Validates DNS propagation
        |
        v
  TLS Provider (Tailscale / ACME)
    - Tailscale: CertPair for .ts.net domains
    - ACME: certmagic + DNS-01 via configured DNS provider
        |
        v
  Proxy serves on https://app.example.com

Quick Start

dnsProviders:
  cloudflare:
    provider: cloudflare
    apiToken: "your-cloudflare-api-token"

defaultDNSProvider: cloudflare

dnsProviders:
  cloudflare:
    provider: cloudflare
    apiTokenFile: "/run/secrets/cloudflare-token"

tlsProviders:
  acme:
    provider: acme
    email: "admin@example.com"

defaultTLSProvider: acme

services:
  myapp:
    image: nginx:alpine
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "myapp"
      tsdproxy.domain: "app.example.com"

DNS Providers

DNS providers manage the CNAME record that points your custom domain to the Tailscale machine. TSDProxy supports the following providers:

Cloudflare

Manages CNAME records and ACME TXT records via the Cloudflare API. Requires an API token with Zone:DNS:Edit and Zone:Zone:Read permissions.

dnsProviders:
  cloudflare:
    provider: cloudflare
    apiToken: "your-cloudflare-api-token"

MagicDNS

The default DNS provider. A no-op provider used when the domain is a .ts.net Tailscale domain. No CNAME management is needed because Tailscale handles DNS resolution internally.

MagicDNS is used automatically and does not need explicit configuration. When tsdproxy.domain ends in .ts.net, TSDProxy selects MagicDNS regardless of the defaultDNSProvider setting.

TLS Providers

TLS providers provision and manage certificates for your custom domains.

Tailscale

Wraps Tailscale’s built-in CertPair for .ts.net domains. Used automatically when the domain ends in .ts.net. No configuration required — the Tailscale TLS provider is resolved per-proxy using the Tailscale local client, regardless of the config entry name.

tlsProviders:
  my-ts-tls:
    provider: tailscale

defaultTLSProvider: my-ts-tls

ACME

Uses certmagic with DNS-01 challenge to provision certificates from Let’s Encrypt (or another ACME compatible CA). The DNS-01 challenge uses the configured DNS provider (e.g. Cloudflare) to create TXT records.

tlsProviders:
  acme:
    provider: acme
    email: "admin@example.com"

Complete Example

A full tsdproxy.yaml with custom domain support:

defaultProxyProvider: default

dnsProviders:
  cloudflare:
    provider: cloudflare
    apiToken: "your-cloudflare-api-token"

tlsProviders:
  acme:
    provider: acme
    email: "admin@example.com"

defaultDNSProvider: cloudflare
defaultTLSProvider: acme
cleanupDNS: true

docker:
  local:
    host: unix:///var/run/docker.sock
    targetHostname: host.docker.internal
    defaultProxyProvider: default

tailscale:
  providers:
    default:
      clientId: "your_client_id"
      clientSecret: "your_client_secret"
  dataDir: /data/

http:
  hostname: 0.0.0.0
  port: 8080

log:
  level: info

A container using the custom domain:

services:
  webapp:
    image: nginx:alpine
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "webapp"
      tsdproxy.domain: "app.example.com"
      tsdproxy.dash.icon: "si/nginx"
      tsdproxy.port.1: "443/https:80/http"

A list proxy using the custom domain:

homepage:
  domain: "home.example.com"
  dnsProvider: cloudflare
  tlsProvider: acme
  ports:
    443/https:
      targets:
        - http://192.168.1.10:3000

Cleanup

When a proxy stops, TSDProxy can automatically remove the DNS CNAME record it created. This is controlled by the cleanupDNS setting:

cleanupDNS: true

Defaults to true. When enabled, the CNAME record is deleted when the proxy shuts down. Set to false to keep DNS records after the proxy stops. TLS certificates are cached by certmagic and reused on next start.

Troubleshooting

domain "app.example.com" set but DNS provider not specified