hostess domains

Description

Manage custom domains for your Hostess projects. Custom domains let you serve your applications from your own domain names (e.g., myapp.com, api.myapp.com) instead of the default *.hostess.run URLs. Hostess automatically provisions TLS certificates for custom domains via Let's Encrypt.

All services also keep their autogenerated *.hostess.run URLs regardless of any custom domain configuration.

Every write (add, update, remove) targets a specific service in a specific environment and routes traffic immediately — no redeploy required. If the target service hasn't been deployed to that environment yet, the domain takes effect automatically on its next deploy. Each command reports which of these happened.

domains list

List all custom domains configured for a project.

Usage

hostess domains list [flags]

Flags

Examples

hostess domains list

DOMAIN              SERVICE      STATUS       DNS
myapp.com           frontend     Active       myapp.com → ingress.hostess.run
api.myapp.com       api          Active       api.myapp.com → ingress.hostess.run
staging.myapp.com   frontend     Pending DNS  staging.myapp.com → ingress.hostess.run

# List domains for a specific project
hostess domains list --project my-other-app

domains add

Add a custom domain to a service in your project.

Usage

hostess domains add <domain> [flags]

Flags

Examples

# Add a domain to the frontend service
hostess domains add myapp.com --service frontend

Domain added.

Configure your DNS:
  Type:  CNAME
  Name:  myapp.com
  Value: ingress.hostess.run

Live routing updated.

# Add an API subdomain
hostess domains add api.myapp.com --service api

# Add to a specific environment
hostess domains add staging.myapp.com --service frontend --env staging

# Add to a specific project
hostess domains add myapp.com --service frontend --project my-app

Routing Outcomes

The line after the DNS configuration reports what happened to live traffic routing:

DNS Configuration

After adding a domain, you need to configure a CNAME record with your DNS provider:

Domain Validation Rules

• Use a valid RFC 1123 hostname: lowercase, no wildcard, and no scheme prefix.
• Keep domain names at or below 253 characters.
• Use each custom domain on one Hostess service.
• Attach custom domains to public application services.

domains update

Retarget an existing domain to a different service and/or environment.

Usage

hostess domains update <domain> [flags]

Flags

At least one of --service or --env is required.

Examples

# Move a domain to a different service
hostess domains update myapp.com --service backend

Domain 'myapp.com' updated.

Live routing updated.

# Move a domain to a different environment
hostess domains update myapp.com --service backend --env staging

domains verify

Trigger DNS verification for a domain.

Usage

hostess domains verify <domain> [flags]

Flags

Examples

hostess domains verify myapp.com

myapp.com is verified.

If verification fails, the command shows the DNS record to point at:

myapp.com is not verified.
Point a CNAME record: myapp.com -> ingress.hostess.run

domains remove

Remove a custom domain from your project.

Usage

hostess domains remove <domain> [flags]

Flags

Examples

hostess domains remove old-domain.com

Domain 'old-domain.com' removed.

Live routing updated.

# Remove from a specific project
hostess domains remove staging.myapp.com --project my-app

Domain Lifecycle

Here's how the domain lifecycle works from start to finish:

1. Add domain — Run hostess domains add myapp.com --service frontend. Traffic starts routing immediately if the service is already live in that environment.
2. Configure DNS — Add a CNAME record pointing myapp.com to ingress.hostess.run
3. DNS verification — Hostess checks DNS periodically, or run hostess domains verify myapp.com to check immediately
4. TLS provisioning — Once DNS is verified, Hostess automatically requests a TLS certificate from Let's Encrypt
5. Active — Domain is live with HTTPS. All traffic to myapp.com routes to your service.

Retarget the domain to a different service or environment at any point with hostess domains update — DNS verification carries over, so status doesn't reset to step 3.

Domain Status Values

You can also configure domains declaratively in your hostess.yml:

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

environments:
  staging:
    domains:
      frontend: [staging.myapp.com]