Set Up Custom Domains

Configure DNS, add custom domains, and verify HTTPS certificates for your services

Every service on Hostess with public or team visibility gets an autogenerated *.hostess.run URL. Custom domains let you serve your app from your own domain.

Hostess automatically provisions and renews HTTPS certificates via Let's Encrypt. There is no manual SSL setup required.

How Custom Domains Work

Adding a domain with hostess domains add or in Studio routes traffic immediately — no redeploy needed. If the target service hasn't been deployed to that environment yet, the domain takes effect automatically on its next deploy. Domains declared in hostess.yml register the same way once you deploy.

Either way:

Hostess registers the domain and prints the DNS target
Let's Encrypt automatically issues an HTTPS certificate once DNS is verified
Traffic flows through the domain to your service

Your autogenerated *.hostess.run URL continues to work alongside any custom domains.

Add a Custom Domain

Choose your domain

Decide which domain or subdomain to use. Common patterns:

Pattern	Example	Best For
Apex domain	`myapp.com`	Marketing sites, landing pages
`www` subdomain	`www.myapp.com`	Web apps (with apex redirect)
API subdomain	`api.myapp.com`	Backend services
Environment subdomain	`staging.myapp.com`	Non-production environments

Add the domain to `hostess.yml`

For production domains, add them directly to the service definition:

hostess.yml

version: "1.0"

services:
  frontend:
    type: nextjs
    build:
      source: ./frontend
    domains:
      - myapp.com
      - www.myapp.com

  api:
    type: fastapi
    build:
      source: ./backend
    domains:
      - api.myapp.com

Service-level domains only apply to the production environment. For staging, preview, or other environments, use environment-level domains (covered below).

Configure your DNS

Create a CNAME record pointing your domain to the DNS target printed by Hostess. For the default Hostess installation, that target is ingress.hostess.run:

Type	Name	Target
ALIAS/ANAME/CNAME flattening	`myapp.com`	`ingress.hostess.run`
CNAME	`www.myapp.com`	`ingress.hostess.run`
CNAME	`api.myapp.com`	`ingress.hostess.run`

If you use Cloudflare, you must set the proxy status to DNS only (grey cloud icon). Cloudflare's proxy intercepts HTTPS traffic and can interfere with Let's Encrypt certificate issuance.

Go to your Cloudflare dashboard
Navigate to DNS > Records
Add a new CNAME record
Set the Name to your domain (e.g., myapp.com or www)
Set the Target to ingress.hostess.run
Turn off the orange cloud — click it so it shows a grey cloud icon ("DNS only")
Click Save

Cloudflare's proxy (orange cloud) must be disabled for Hostess domains. If the orange cloud is enabled, Let's Encrypt cannot verify your domain and certificate issuance will fail. Always use DNS only mode (grey cloud).

For most DNS providers (Namecheap, Google Domains, Route 53, GoDaddy, etc.):

Log in to your DNS provider's dashboard
Navigate to your domain's DNS settings
Add a new CNAME record
Set the Host / Name to the subdomain (e.g., www, api, or @ for apex)
Set the Value / Points to to ingress.hostess.run
Set the TTL to Auto or 300 (5 minutes)
Save the record

Some DNS providers don't support CNAME records on apex domains (e.g., myapp.com without a subdomain). In that case, check if your provider supports ALIAS or ANAME records, which work the same way. If not, consider using a www subdomain with a redirect from the apex.

Deploy to apply the domain

Deploy your project to register the domain with Hostess:

Terminal

hostess deploy

Hostess registers domains from hostess.yml during the deploy process. You can also add a domain without changing YAML by running hostess domains add myapp.com --service=frontend --env=production — this routes traffic immediately if frontend is already deployed to production, and takes effect automatically the next time it deploys otherwise.

Verify HTTPS

After deploying and configuring DNS, Hostess automatically provisions an HTTPS certificate via Let's Encrypt. This typically takes 1-3 minutes after DNS propagates.

Visit your domain in a browser and check for the padlock icon:

https://myapp.com       ✓ Secure
https://api.myapp.com   ✓ Secure

Your autogenerated URL continues to work as well:

https://my-app-frontend-k7xm9p2q.hostess.run   ✓ Still active

Per-Environment Domains

For non-production environments (staging, preview, etc.), configure domains under the environments section:

hostess.yml

version: "1.0"

environments:
  production:
    domains:
      frontend: [myapp.com, www.myapp.com]
      api: [api.myapp.com]
  staging:
    domains:
      frontend: [staging.myapp.com]
      api: [api-staging.myapp.com]

services:
  frontend:
    type: nextjs
    build:
      source: ./frontend

  api:
    type: fastapi
    build:
      source: ./backend

In this configuration:

Production serves from myapp.com and api.myapp.com
Staging serves from staging.myapp.com and api-staging.myapp.com
Environments without domains configured use autogenerated *.hostess.run URLs

Environment-level domains override service-level domains for that environment. If you define domains under both services.frontend.domains and environments.production.domains.frontend, the environment-level configuration takes precedence.

Domain Rules

A domain can only appear in one environment — it must be globally unique
Service-level domains is shorthand for production only
Non-production environments get custom domains when explicitly listed under environments
Custom domains attach to web-facing services (your apps and APIs)

Multiple Domains on One Service

You can attach multiple domains to a single service. This is common for apex + www setups:

hostess.yml

services:
  frontend:
    type: nextjs
    build:
      source: .
    domains:
      - myapp.com
      - www.myapp.com

Both domains will route to the same service. Create CNAME records for each:

Type	Name	Target
ALIAS/ANAME/CNAME flattening	`myapp.com`	`ingress.hostess.run`
CNAME	`www.myapp.com`	`ingress.hostess.run`

Troubleshooting

DNS not propagating

DNS changes can take up to 48 hours to propagate globally, though most providers update within 5-30 minutes. You can check propagation status using:

Terminal

# Check if your CNAME is resolving
dig myapp.com CNAME +short

# Example output:
# ingress.hostess.run.

If dig returns nothing or the wrong value, your DNS change hasn't propagated yet. Wait and try again.

HTTPS certificate not issuing

Let's Encrypt needs to verify domain ownership before issuing a certificate. Common reasons for failure:

DNS not propagated yet — Wait 5-30 minutes after creating the CNAME record
Cloudflare proxy enabled — Disable the orange cloud (use DNS only / grey cloud)
Wrong CNAME target — Verify you pointed to ingress.hostess.run (not hostess.run)
Domain not in hostess.yml — Make sure the domain appears in your configuration and you have deployed

Domain shows "Not Secure"

If your domain loads but shows a security warning:

The certificate may still be issuing — wait 1-3 minutes and refresh
Check that you're visiting https:// not http://
Clear your browser cache or try an incognito window

Domain validation constraints

Hostess validates domains during deployment. A valid domain:

Is a valid RFC 1123 hostname of up to 253 characters
Names an exact host — myapp.com, www.myapp.com, or api.myapp.com
Is a bare hostname — enter myapp.com rather than https://myapp.com
Is globally unique across all environments and services

Hostess normalizes domains to lowercase.

On this page