URL Routing

Overview

Hostess gives public application services generated HTTPS URLs and keeps private services reachable from other services through magic variables. You can also attach custom domains when you want branded URLs.

There are several types of URLs in Hostess:

Auto-Generated URL Format

Public application services and public ports receive stable URLs on the hostess.run domain using this format:

https://{project}-{service}-{nanoID}.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)
• {nanoID} is an 8-character alphanumeric identifier, generated once per service in the environment

Examples

https://my-app-frontend-k7xm9p2q.hostess.run
https://my-app-api-a3x9d2m1.hostess.run
https://my-app-minio-p4k8n7v2.hostess.run

These URLs use HTTPS with certificates provisioned automatically.

NanoID

The NanoID is an 8-character alphanumeric string (e.g., k7xm9p2q) that identifies a service in an environment. Key characteristics:

• Generated once — The NanoID is created when a service is first deployed in an environment and persists across subsequent deployments.
• Stable — The same service keeps the same NanoID in that environment, so stable URLs stay consistent between deploys.
• URL-safe — Contains alphanumeric characters and is normalized into the generated hostname.

Because the NanoID 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 public traffic. They route to the active version of a public service.

https://my-app-api-a3x9d2m1.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 public service URLs.
• 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 application services and public ports. When git metadata is available, they use the short git commit SHA instead of the NanoID:

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 ports, each public port gets its own URL. The first public port uses the standard URL format. Subsequent public ports get a suffix:

Port 1 (primary): https://{project}-{service}-{nanoID}.hostess.run
Port 2:           https://{project}-{service}-{nanoID}-2.hostess.run
Port 3:           https://{project}-{service}-{nanoID}-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
        public: true
      - port: 9001
        public: true

The resulting URLs:

S3 API (port 1):   https://my-app-minio-p4k8n7v2.hostess.run
Web Console (port 2): https://my-app-minio-p4k8n7v2-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-a3x9d2m1.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 service:

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

See Custom Domains for the full setup guide, including DNS configuration and TLS certificates.

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 publicly accessible, 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. The target service or port should be public:

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-a3x9d2m1.hostess.run

  api:
    type: fastapi
    public: true
    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 public service URLs and connection guidance for private services:

$ hostess deploy

✓ Deployment complete

frontend: https://my-app-frontend-k7xm9p2q.hostess.run
api:      https://my-app-api-a3x9d2m1.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-k7xm9p2q.hostess.run
  api              fastapi    Ready      https://my-app-api-a3x9d2m1.hostess.run
  database         postgres   Ready      (private)

External URLs:
  frontend:        https://my-app-frontend-k7xm9p2q.hostess.run
  api:             https://my-app-api-a3x9d2m1.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.