URL Routing

Overview

Hostess gives generated HTTPS URLs for application services with public or team-scoped visibility. Private services stay reachable from other services through magic variables (and locally via hostess connect). You can also attach custom domains when you want branded URLs.

There are several types of URLs in Hostess:

Auto-Generated URL Format

Application services and ports with public or team visibility receive stable URLs on the hostess.run domain using this format:

https://{project}-{service}-{slug}.hostess.run

Where:

• {project} is your project name (from the name field in hostess.yml or the project name in Studio)
• {service} is the service name (the key in your services map)
• {slug} is a short friendly identifier generated once per service in the environment (two words joined with a hyphen, for example able-arc)

Examples

https://my-app-frontend-able-arc.hostess.run
https://my-app-api-calm-brook.hostess.run
https://my-app-minio-quiet-harbor.hostess.run

These URLs use HTTPS with certificates provisioned automatically. Team URLs use the same format and require Hostess sign-in before the app loads.

Service slug

The slug is a human-readable, DNS-safe label (for example able-arc) that identifies a service in an environment. Key characteristics:

• Generated once — Hostess creates the slug when a service is first deployed in an environment and keeps it for later deployments.
• Stable — The same service keeps the same slug in that environment, so stable URLs stay consistent between deploys.
• URL-safe — Lowercase words suitable for hostnames.

Because the slug persists, you can share service URLs, bookmark them, or use them in webhook configurations.

Stable URLs

Stable URLs are the primary generated URLs you share with users, configure in callbacks, and use for browser traffic. They route to the active version of a public or team service.

https://my-app-api-calm-brook.hostess.run

How Stable URLs Work

When you deploy a new version of your service:

1. Hostess builds and starts the new version alongside the existing one.
2. The new version goes through health checks.
3. Once the new version is healthy, the stable URL is updated to route traffic to it.
4. The stable URL continues pointing to the active version until the new version is ready.

This keeps stable URLs pointed at the active version while new deployments are prepared and checked.

Accessing Stable URLs

Stable URLs are displayed in several places:

• Deploy output — After a successful hostess deploy, the CLI prints service URLs for public and team services.
• Studio — The project dashboard and service detail pages show service URLs.
• hostess inspect — Run this command to see deployment details and URLs.

Deployment URLs

Deployment URLs are generated for public and team application services (and matching ports). When git metadata is available, they use the short git commit SHA instead of the service slug:

https://{project}-{service}-{shortSHA}.hostess.run

Where {shortSHA} is the first 7 characters of the git commit SHA. When git metadata is unavailable, Hostess uses a deployment-specific fallback suffix.

Examples

https://my-app-frontend-a1b2c3d.hostess.run
https://my-app-api-a1b2c3d.hostess.run

When to Use Deployment URLs

Deployment URLs are useful for:

• Rollback verification — Before rolling back, visit the deployment URL of the previous version to confirm it still works correctly.
• PR previews — Pull request deployments get deployment URLs, so reviewers can see what that PR's changes look like.
• Debugging — Compare the behavior of two different deployments side by side by visiting their deployment URLs.
• Audit trail — Deployment URLs make it easy to revisit a deployed version while that deployment is retained.

Deployment URL Lifetime

Unlike stable URLs, deployment URLs are useful for reviewing a deployed version directly. If you deploy the same commit again, Hostess may reuse the same commit-based URL host for the newer deployment of that commit.

Multi-Port URLs

When a service exposes multiple public or team ports, each of those ports gets its own URL. The first such port uses the standard URL format. Subsequent ports get a suffix:

Port 1 (primary): https://{project}-{service}-{slug}.hostess.run
Port 2:           https://{project}-{service}-{slug}-2.hostess.run
Port 3:           https://{project}-{service}-{slug}-3.hostess.run

Example: MinIO

MinIO exposes an S3 API on port 9000 and a web console on port 9001:

services:
  minio:
    type: custom
    image: minio/minio:latest
    command: ["server", "/data", "--console-address", ":9001"]
    ports:
      - port: 9000
        visibility: public
      - port: 9001
        visibility: public

The resulting URLs:

S3 API (port 1):   https://my-app-minio-quiet-harbor.hostess.run
Web Console (port 2): https://my-app-minio-quiet-harbor-2.hostess.run

Port Numbering Convention

• Port 1 is the first port in the ports list. It has no suffix and is the default port.
• Port 2, 3, etc. correspond to the second, third, and subsequent ports in the list. They get a -2, -3, etc. suffix.

This numbering is also used in magic variables: ${minio.port_1.url}, ${minio.port_2.external_url}, etc.

Custom Domain URLs

Custom domains point to the same service as generated URLs. When you configure a custom domain like api.myapp.com, it routes to the same service that my-app-api-calm-brook.hostess.run routes to.

Both URLs work simultaneously. The generated URL remains available after you add a custom domain.

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

After deploying a public or team service:

Auto-generated: https://my-app-api-calm-brook.hostess.run
Custom domain:  https://api.myapp.com                     ← works after DNS setup

Adding, retargeting, or removing a domain through Studio or hostess domains updates routing immediately — no redeploy needed. If you retarget a domain to a different service or environment, the change takes effect right away and DNS verification carries over.

Team services keep Hostess sign-in on both the generated URL and any custom domain. See Custom Domains for the full setup guide, including DNS configuration and TLS certificates. For who can open team URLs, see Service Visibility.

Internal URLs

Internal URLs are used for service-to-service communication within your stack. Use magic variables such as ${api.url} instead of hard-coding an internal hostname.

Internal URL magic variables resolve at deploy time:

API_URL: ${api.url}

For multi-port services, use port-specific variables:

MINIO_API_URL: ${minio.port_1.url}
MINIO_CONSOLE_URL: ${minio.port_2.url}

When to Use Internal URLs

Use internal URLs (via ${service.url}) whenever both the caller and the callee are Hostess services:

services:
  frontend:
    type: nextjs
    build:
      source: ./frontend
    env:
      # Server-side rendering calls the API internally
      API_URL: ${api.url}

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

Internal URLs are the right default for server-side service-to-service calls because they stay within your Hostess environment.

External URLs

External URLs are the HTTPS URLs that users, browsers, webhooks, and external services use to reach your services. They include both auto-generated *.hostess.run URLs and custom domains.

When to Use External URLs

Use external URLs (via ${service.external_url}) when the caller is outside Hostess:

services:
  frontend:
    type: nextjs
    build:
      source: ./frontend
    env:
      # Browser JavaScript calls the API via the external URL
      NEXT_PUBLIC_API_URL: ${api.external_url}
      # → https://my-app-api-calm-brook.hostess.run

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

Common scenarios for external URLs:

URL Discovery

There are several ways to find your service URLs:

Deploy Output

After a successful deployment, the CLI prints URLs for public and team services and connection guidance for private services:

$ hostess deploy

✓ Deployment complete

frontend: https://my-app-frontend-able-arc.hostess.run
api:      https://my-app-api-calm-brook.hostess.run
database: connection info available via `hostess inspect dep_abc123`

hostess inspect

View deployment URLs and service information:

$ hostess inspect

Deployment: dep_abc123
Status:     Ready
Branch:     main
Commit:     a1b2c3d
Created:    5m ago
Completed:  2m ago

Services:
  NAME             TYPE       STATUS     URL
  ──────────────────────────────────────────────────────────────────────
  frontend         nextjs     Ready      https://my-app-frontend-able-arc.hostess.run
  api              fastapi    Ready      https://my-app-api-calm-brook.hostess.run
  database         postgres   Ready      (private)

External URLs:
  frontend:        https://my-app-frontend-able-arc.hostess.run
  api:             https://my-app-api-calm-brook.hostess.run

Private Services:
  database:        postgres — use: hostess connect database

Studio

The project dashboard in Hostess Studio displays all service URLs with clickable links. The deployment detail page shows both stable and deployment-specific URLs.

URL Routing Summary

Here is a complete reference of all URL types and when to use each:

Magic Variable Quick Reference

See Magic Variables for the complete reference.