Skip to content

Custom domains

Serve a web service or static site on your own domain, with an HTTPS certificate HostStack issues and renews for you.

Two ways to set up DNS

Every web service already has a *.hoststack.dev hostname. To add your own, the domain's DNS has to point at HostStack, and there are two ways to arrange that:

Keep DNS where it isHost DNS on HostStack
HowAdd a CNAME record at your current DNS provider.Register or transfer the domain under Domains, or use Connect existing and change its nameservers to ns1.hoststack.dev and ns2.hoststack.dev.
VerificationYou click Verify once the record resolves.Automatic: HostStack writes the record and verifies the domain when you add it.
Apex (example.com)An A record to HostStack's fixed address, or ALIAS / CNAME flattening.Works like any other name.

Either way, the domain is then attached to a service the same way, described next.

Add a domain

  1. Attach the hostname to the service

    Open the service, go to Settings → Custom Domains and click Add domain. Enter the hostname, such as app.example.com, and pick the service. Leave Path prefix empty unless you are splitting a hostname.

  2. Point DNS at HostStack

    If HostStack hosts the domain's DNS, skip this step — the record is created for you. Otherwise, add a CNAME at your DNS provider (below).

  3. Verify

    HostStack re-checks a pending domain on its own — every minute for the first hour after you add it, then every 15 minutes — so it turns Active shortly after the record resolves. Click Verify to check straight away instead.

  4. Wait for the certificate

    As soon as the domain verifies, HostStack redeploys the service's current image — no rebuild — to route the hostname, and Let's Encrypt issues the certificate, normally within a minute or two — open https:// on the domain to check. HostStack watches for the certificate on the same schedule, and the SSL column turns Active once it is served.

hoststack domains add app.example.com --service svc_...
# add the DNS record, then:
hoststack domains verify app.example.com
hoststack domains list

Apex domains (example.com) and subdomains are both accepted. Wildcard domains (*.example.com) are not: certificates are issued with the HTTP-01 challenge, which cannot issue a wildcard. Add each subdomain on its own.

The DNS record

For a subdomain, add a CNAME record pointing at the service's *.hoststack.dev hostname, shown at the top of the service page:

DNS record
Type:   CNAME
Name:   app            (app.example.com)
Value:  web-a1b2.hoststack.dev

Verification accepts a CNAME to any hostname under hoststack.dev — the dashboard suggests hoststack.dev itself, which works too. Remove any A or AAAA record on the same name first; a name can't have both.

Verify with a TXT record instead

When a CNAME isn't possible — an apex with CNAME flattening, or a proxy in front — prove ownership with a TXT record instead. Expand the domain's row in the dashboard to copy its verification token, and publish it as a TXT record on the hostname itself, either as the bare token or as hoststack-verify=<token>. The token is unique to that domain; removing and re-adding the domain issues a new one.

A TXT record only proves ownership. The name must still resolve to HostStack — through the CNAME, ALIAS or flattened record — before a certificate can be issued and traffic can arrive.

Apex domains

DNS doesn't allow a CNAME on the apex (example.com without www), because the apex also carries the domain's NS and MX records. In order of preference:

  • Host the DNS on HostStack. The apex gets its address records automatically when you add it to a service.
  • Add an A record to HostStack's ingress address (table below). This works at every DNS provider, including the many — Simply.com, one.com and most Danish hosts — that have no ALIAS. Verify with the TXT record, because an A record carries no proof of ownership.
  • Use ALIAS, ANAME or CNAME flattening if your DNS provider has it (Cloudflare flattens the apex on every plan), pointing at the service's *.hoststack.dev hostname. Verify with the TXT record, because the CNAME check can't see through flattening.
  • Serve on www and use your DNS provider's URL forwarding to send the apex there.

DNS targets for an apex

TypeNameValue
A@204.168.149.149
TXT@hoststack-verify=<token>

204.168.149.149 is HostStack's ingress for every service, wherever it runs, and it is the same address HostStack writes into every zone it hosts. It does not change when a service is redeployed, moved or scaled. If it ever has to change, it will be announced well in advance.

There is no AAAA (IPv6) target yet: the ingress is IPv4-only. Don't add an AAAA record on the apex, and remove one left over from a previous host — a browser that prefers IPv6 would go there instead of HostStack, and Let's Encrypt may validate over IPv6 and fail.

Follow a domain from your code

A platform that adds its customers' domains through the API can show each domain's progress — waiting for DNS, verified, certificate ready — without polling. Every domain carries status and certStatus, returned by GET /api/domains/:teamId and GET /api/domains/:teamId/:domainId:

status

pending → active once verified, or failed after seven days without verifying.

certStatus

none until the domain is verified, then pending → issued. failed carries the reason in certError and a code in certErrorCode (caa, dns, challenge_failed, rate_limited, unknown); issuance is still retried, and a later success moves it to issued. disabled when HTTPS is turned off for the domain.

certIssuedAt, sslCertExpiry

When the served certificate was issued and when it expires.

Subscribe a webhook (Settings → Webhooks) to domain.verified, domain.failed, domain.cert_issued, domain.cert_failed and domain.removed. Each fires when the domain's state changes — domain.cert_failed again only if the reason changes — and every one carries the same data, so the last event received is the domain's current state:

json
{
  "type": "domain.cert_failed",
  "created_at": "2026-11-18T12:04:00.000Z",
  "data": {
    "domainId": 812,
    "publicId": "dom_...",
    "domain": "shop.example.dk",
    "serviceId": 145,
    "status": "active",
    "sslStatus": "failed",
    "certExpiresAt": null,
    "reasonCode": "caa",
    "reason": "The CAA records on example.dk allow only digicert.com, so Let's Encrypt cannot issue a certificate. Add a CAA record: example.dk CAA 0 issue \"letsencrypt.org\"."
  }
}

sslStatus is the domain's certStatus. reason is set on domain.cert_failed and domain.failed.

Primary domain, HTTPS and redirects

Choose Edit Settings from a domain's menu, or use hoststack domains update:

Primary Domain

The hostname that stands for the service: what ${{service.url}} resolves to, what its uptime check probes, and what its monitoring page shows. One per service. With none chosen, the oldest domain is used — on a renamed site that is usually the old name that now redirects. CLI: --primary.

Enable SSL (HTTPS)

On by default: the domain gets a certificate and plain HTTP redirects to HTTPS. Turn it off only to serve HTTP. Changing it redeploys the service's current image. CLI: --ssl / --no-ssl.

Redirect URL

Instead of serving the service, answer every request with a permanent (308) redirect to this URL, keeping the path. Use it to send www.example.com to example.com, or an old domain to a new one. The domain still gets its own certificate. CLI: --redirect https://example.com / --no-redirect.

Strip trailing slash on redirects

Off by default. When on, the redirects HostStack answers for this domain (the redirect URL above, and plain HTTP to HTTPS) drop a trailing slash in the same hop, so http://www.example.com/about/ reaches https://example.com/about in one redirect rather than two. Turn it on when your app's URLs have no trailing slash (the default in TanStack Start, Next.js and Astro). Leave it off if your app adds one, or the two would redirect back and forth. Requests that reach your app over HTTPS are never rewritten, and no path is exempt. CLI: --strip-trailing-slash / --keep-trailing-slash.

bash
hoststack domains update example.com --primary
hoststack domains update www.example.com --redirect https://example.com
hoststack domains update www.example.com --strip-trailing-slash

Certificates come from Let's Encrypt and are renewed automatically before they expire; there is nothing to configure.

Share one hostname between services

To serve example.com from a frontend and example.com/api from a backend, attach the hostname twice: once with no path prefix to the frontend, and once with /api as the Path prefix to the backend. The more specific prefix wins for the paths it matches, without any priority to configure.

bash
# Everything else goes to the frontend service
hoststack domains add example.com --service svc_...

# /api and everything under it goes to the backend service
hoststack domains add example.com --service svc_... --path-prefix /api
  • The prefix is not stripped: the backend receives /api/users, not /users.
  • A prefix starts with /, has at least one segment (/ alone is the catch-all, expressed by leaving the prefix empty) and uses URL-safe characters only — no * globs or query strings.
  • Each attachment has its own Verify, but the same DNS record satisfies both, and one certificate covers the hostname.
  • A hostname attached by one team can't be attached by another.

Search engines and the platform URL

A service's free *.hoststack.dev hostname is served with X-Robots-Tag: noindex, nofollow, so search engines leave it out. A custom domain is always indexable and never affected by this — attach the domain you want to rank on, and it ranks. The default stops your site competing with itself: indexed on both hostnames, the same pages exist at two addresses and search engines pick which one to show.

If the site has no custom domain and you do want the platform hostname indexed, turn on Allow search engines to index the platform URL under Settings → Custom Domains → Search Engine Indexing. It applies on the next deploy. Dev boxes and preview deploys are always kept out of search results.

Move or remove a domain

A domain can't be switched to another service in place. Delete it from the first service and add it to the second; with DNS elsewhere, verify it again.

Deleting a domain stops it being served straight away and releases its certificate. If HostStack created its DNS record, that record is deleted too.

Troubleshooting

Still Pending after Verify

Check what the world sees with dig +short app.example.com CNAME. No answer usually means the record hasn't propagated yet — normally minutes, occasionally hours — or a proxy is hiding it. HostStack keeps re-checking on its own. A domain that still can't be verified seven days after it was added is marked failed; delete it and add it again.

Registry still points elsewhere

HostStack hosts the zone and its records are right, but the domain's registrar still delegates it to other nameservers. Change the nameservers at the registrar to ns1.hoststack.dev and ns2.hoststack.dev, then verify again. The verify result names the nameservers it found.

SSL shows Not issued

No certificate has been seen on the domain a day and a half after it was verified. Let's Encrypt has to reach the domain over plain HTTP on port 80: make sure the name still resolves to HostStack and nothing in front of it blocks /.well-known/acme-challenge/.

Certificate failed: CAA

A CAA record on the domain, or on a parent such as example.dk for shop.example.dk, names other certificate authorities only. Add CAA 0 issue "letsencrypt.org" next to them; HostStack notices within 15 minutes and the certificate follows.

Too many redirects

A proxy in front — typically Cloudflare with SSL/TLS set to Flexible — calls HostStack over HTTP, which redirects to HTTPS, forever. Set it to Full.

Already attached to another team

The hostname is in use by a different team. If it is yours, contact support.

Next steps

Was this page helpful?