Custom domains

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:

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

   Click Verify next to the domain once the record resolves. HostStack does not re-check on its own, so if it is still Pending, wait a few minutes and verify again.

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. The SSL column shows Issuing until a daily check has read the served certificate, then Active.

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

// hs and teamId as in the Quickstart
const { domain } = await hs.domains.add(teamId, {
  domain: 'app.example.com',
  serviceId: 'svc_...',
});

// after adding the DNS record:
const { domain: checked } = await hs.domains.verify(teamId, domain.id);
console.log(checked.status); // "active" once verified

Attach app.example.com to the service svc_..., tell me which
DNS record to add, and verify it once I've added it.

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:

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.
• 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.

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.

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.

# 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. 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/.

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

• NetworkingPrivate addresses between services and what the edge adds to requests.
• Uptime checksProbe the primary domain and get alerted when it goes down.
• Environment variablesHand the service its own address with ${{service.url}}.