Configuration Reference

The hostess.yml file is the single source of truth for your application. It defines what services run, how they connect, where they deploy, and how they scale. One file describes your entire stack.

Design Principles

Hostess configuration follows four principles:

• Declarative — You describe the desired state of your stack, not the steps to achieve it. Hostess figures out the "how".
• Minimal — Only specify what matters. Smart defaults handle everything else. A simple app needs only a few lines.
• Portable — Your configuration is not tied to any specific cloud provider, orchestrator, or hosting platform.
• Readable — Non-engineers should be able to read your hostess.yml and understand the basics of your stack.

Top-Level Fields

Every hostess.yml file starts with these top-level fields:

version: "1.0"
name: my-app
description: A description of my application
environments:
  production:
    domains:
      web: [my-app.example.com]
services:
  # ... your services
jobs:
  # ... one-off, scheduled, or manual jobs

Field Reference

Only version and services are required. Everything else has sensible defaults.

Services

Services are the core of your hostess.yml file. Each service defines a component of your application — a web frontend, an API backend, a database, a cache, a worker process, or any containerized application.

services:
  frontend:
    type: nextjs
    build:
      source: ./frontend
  backend:
    type: fastapi
    build:
      source: ./backend
  database:
    type: postgres
    resources: large

Each service is keyed by a name (the YAML key under services:). Names must be at least 2 and at most 63 characters, use lowercase letters, digits, and hyphens only, start with a letter, and end with a letter or number.

Full ServiceSpec Reference

Service Types

The type field tells Hostess what kind of service you are running. This enables smart defaults for ports, health checks, resource allocation, and more.

type: nextjs | fastapi | postgres | redis | custom

Supported Types

Web framework types (nextjs, fastapi) require one of build, image, or source to be specified. They produce container deployments that receive HTTP traffic.

Database types (postgres, redis) are fully managed by Hostess. You do not need to provide build or image — Hostess provisions the database automatically. Database services support resources, retention, backups, and databases (scoped databases) fields.

Build Configuration

Every non-database service needs to tell Hostess where its code is. You have three options:

• source — zero-config. Point at a directory and Hostess builds it for you, no Dockerfile required (the simplest path).
• build — build from your own Dockerfile, when you need full control.
• image — use a pre-built, public container image.

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

source: .

source: ./services/worker

services:
  backend:
    type: fastapi
    build:
      source: ./backend
      dockerfile: Dockerfile.prod
      args:
        NODE_ENV: production
        BUILD_VERSION: "1.2.3"

build:
  source: .

build:
  source: ./services/auth

build:
  source: ./backend
  dockerfile: Dockerfile.prod
  args:
    PYTHON_VERSION: "3.12"

services:
  backend:
    type: custom
    image: ghcr.io/myorg/backend:v1.2.3

image: nginx:1.25

image: ghcr.io/myorg/my-service:latest

image: registry.example.com/team/service:v2.0.0

Environment Variables

The env field defines environment variables for your service. Hostess supports three types of values:

services:
  backend:
    type: fastapi
    env:
      # Literal values
      LOG_LEVEL: info
      NODE_ENV: production

      # Magic variables — automatic service discovery
      DATABASE_URL: ${database.url}
      CACHE_URL: ${cache.url}
      FRONTEND_URL: ${frontend.external_url}

      # Secret references — values from the Hostess secret store
      JWT_SECRET: ${secret:JWT_SECRET}
      STRIPE_KEY: ${secret:STRIPE_API_KEY}

Value Types

Dependencies

The depends_on field declares that your service depends on other services. Hostess uses it for deployment ordering and to wait before starting a dependent service’s runtime instances.

services:
  backend:
    type: fastapi
    depends_on:
      - database
      - cache
    env:
      DATABASE_URL: ${database.url}
      CACHE_URL: ${cache.url}

  database:
    type: postgres

  cache:
    type: redis

Use object form when you need to make the dependency condition explicit or depend on a top-level job:

services:
  backend:
    type: fastapi
    depends_on:
      database:
        condition: healthy
      migrate-db:
        condition: completed

jobs:
  migrate-db:
    image: ghcr.io/acme/api:latest
    command: ["alembic", "upgrade", "head"]
    run: on_deploy

Behavior

• Startup order — Dependent services are rolled out after their dependencies in the graph.
• Waiting — For HTTP services (for example nextjs / fastapi / custom with an HTTP health check), Hostess waits until the configured HTTP health path responds. For Postgres and Redis, it waits until the dependency accepts connections on the database port.
• Job gates — A service can depend on a top-level job with condition: completed, so migrations or setup jobs finish before the service starts.
• Magic variables — Values like ${database.url} are resolved from the stack configuration; list dependencies in depends_on when you need strict ordering relative to those services.
• Deployment order — Dependencies must form a directed acyclic graph (no cycles).

Validation

• No circular dependencies — If service A depends on B and B depends on A, validation fails.
• References must exist — Every target listed in depends_on must be defined in services or jobs.
• No self-references — A service cannot depend on itself.
• Typed conditions — healthy is valid for service targets; completed is valid for job targets.
• Gating jobs only — Services can depend on jobs that complete automatically as part of a deploy; manual and cron jobs run outside the deploy flow.

File Mounts

Use files when a service image expects a read-only config file, certificate, policy, or key at a specific path.

services:
  gateway:
    type: custom
    image: ghcr.io/acme/gateway:1.0.0
    files:
      - name: gateway-config
        mount: /etc/gateway/config.yml
        source: ./gateway/config.yml
      - name: signing-key
        mount: /etc/gateway/signing.key
        secret: GATEWAY_SIGNING_KEY
        mode: "0400"

Exactly one of source, content, or secret must be set. File mounts are single files, not directories, and are read-only at runtime.

Domains

Custom domains give your services memorable, branded URLs instead of the auto-generated *.hostess.run addresses.

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

Behavior

• Automatic HTTPS — Hostess automatically provisions TLS certificates via Let's Encrypt for all custom domains.
• Auto-generated URLs always exist — Every service gets a *.hostess.run URL regardless of custom domains.
• Web-facing services — Attach custom domains to services that serve HTTP traffic (your apps and APIs).
• DNS setup required — You need to create a CNAME record pointing your domain to the Hostess routing endpoint:

CNAME myapp.com → ingress.hostess.run

Validation Rules

• Must be valid RFC 1123 hostnames — exact, lowercase names like myapp.com or api.myapp.com
• Maximum 253 characters
• Globally unique — a domain cannot appear in multiple services or environments
• No duplicates within a single service

Visibility

The visibility field controls who can open a service’s HTTPS URL:

Defaults: nextjs → public; other types → private. Set visibility: team explicitly when you want a sign-in–gated URL.

services:
  dashboard:
    type: nextjs
    build:
      source: ./dashboard
    visibility: team

Full behavior, Studio Access activity, and custom-domain notes are in Service Visibility.

Ports

The ports field specifies which ports your service exposes. Most of the time you do not need to set this — the service type provides a sensible default.

services:
  backend:
    type: fastapi
    ports: [8000]

Default Ports by Type

When to Override

You need to set ports when:

• Your application listens on a non-default port
• You expose multiple ports (e.g., an application port and a metrics port)
• You are using the custom service type

Multi-Port Services

Some services expose multiple ports. List them all, and optionally set visibility per port:

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

Each public or team port gets its own external URL:

Port 1 (9000): https://my-app-minio-quiet-harbor.hostess.run
Port 2 (9001): https://my-app-minio-quiet-harbor-2.hostess.run

You can reference individual ports using magic variables: ${minio.port_1.url}, ${minio.port_2.url}, ${minio.port_2.external_url}, etc.

Resources

The resources field controls how much CPU, memory, and storage your service gets. Hostess offers convenient presets and also supports explicit values.

services:
  backend:
    type: fastapi
    resources: medium

services:
  database:
    type: postgres
    resources:
      preset: large
      storage: 200Gi

services:
  ml-inference:
    type: custom
    resources:
      cpu: 4.0
      memory: 16Gi

  database:
    type: postgres
    resources:
      cpu: 2.0
      memory: 4Gi
      storage: 100Gi

Replicas and Autoscaling

The replicas field controls how many instances of your service run. You can set a fixed number or configure horizontal autoscaling.

services:
  worker:
    type: custom
    replicas: 3

services:
  backend:
    type: fastapi
    replicas:
      min: 2
      max: 10
      target_cpu: 70

Validation

• Fixed replica count and autoscaling min must be at least 1.
• Autoscaling max must be greater than or equal to min.

Health Checks

Health checks tell Hostess how to determine if your service is running correctly. Hostess uses them to decide when a replica is ready to receive traffic, to restart replicas that stop responding, and to gate safe rollouts.

services:
  backend:
    type: fastapi
    health:
      http: /api/healthz
      interval: 10s
      timeout: 2s
      retries: 5

services:
  worker:
    type: custom
    health:
      command: "pgrep -f worker_process"
      interval: 30s
      timeout: 5s
      retries: 3

Health Check Fields

When you omit the entire health block, Hostess uses the built‑in defaults for your service type (see below). Those defaults use a 30s check interval.

When you set a health block, you can tune the check with interval, timeout, and retries. If you omit interval in your health block, the check runs on a 10s interval (other fields still default as in the table).

Default Health Checks by Type

If you do not define health, each service type gets a built‑in check with a 30s interval:

You only need to set health if you want to override the default or if you are using the custom type.

Lifecycle Hooks

Lifecycle hooks let you run custom commands at specific points in your service's lifecycle — before startup, during deployment, after deployment, and during shutdown.

services:
  backend:
    type: fastapi
    lifecycle:
      init:
        command: ["python", "manage.py", "collectstatic", "--noinput"]

      migrate:
        command: ["alembic", "upgrade", "head"]
        timeout: 10m

      post_deploy:
        command: ["python", "scripts/warmup_cache.py"]

      shutdown:
        timeout: 30s
        command: ["python", "scripts/cleanup.py"]

Hook Reference

Commands should be YAML arrays, with each item representing one argv segment. migrate.timeout and post_deploy.timeout default to 5m when omitted.

Retention and Persistence

The retention field controls whether data for postgres, redis, and stateful custom workloads should persist across redeploys or can be discarded with the environment.

services:
  database:
    type: postgres
    retention: permanent

Set retention explicitly for each service that supports it — the retention field decides whether data persists, regardless of the environment name.

For custom services, retention: permanent is shorthand for one durable mount at /data, sized from the service resource preset. Use persistence when the image needs a different mount path, a specific size, ownership initialization, or multiple durable directories.

services:
  minio:
    type: custom
    image: minio/minio:latest
    command: ["server", "/data"]
    ports: [9000]
    retention: permanent

services:
  n8n:
    type: custom
    image: docker.n8n.io/n8nio/n8n:stable
    ports: [5678]
    persistence:
      mount: /home/node/.n8n
      size: 10Gi
      owner: "1000:1000"

services:
  cms:
    type: custom
    image: ghcr.io/acme/cms:latest
    ports: [8080]
    persistence:
      - name: data
        mount: /var/lib/cms
        size: 20Gi
      - name: uploads
        mount: /app/uploads
        size: 100Gi
        owner: "1000:1000"

Persistence Fields

Validation rejects persistence on non-custom services, retention: ephemeral combined with explicit persistence, duplicate mount paths, unsafe paths, and files mounted inside persistent directories.

Insights

The insights field controls whether Hostess collects traffic, latency, error-rate, and trace data for the service. Insights are on by default — this field exists only to turn collection off. You never have to configure anything to get insights.

services:
  backend:
    type: fastapi
    insights: disabled        # shorthand: turn off all insights for this service

Use the object form for finer control:

services:
  web:
    type: nextjs
    insights:
      server: disabled        # no server-side metrics or traces collected
      browser: disabled       # no browser analytics collected

Fields

The scalar shorthand insights: disabled disables both server and browser. insights: enabled and an absent block are equivalent.

Logs

The logs field tells Hostess how to parse your service's log output.

services:
  backend:
    type: fastapi
    logs: structured        # parse stdout/stderr as structured JSON

Backups

The backups field configures automatic backups for database and custom services.

services:
  database:
    type: postgres
    backups: daily

services:
  database:
    type: postgres
    backups:
      schedule: daily
      retention: 14

services:
  database:
    type: postgres
    backups:
      schedule: "0 3 * * *"   # Every day at 3 AM
      retention: 30

services:
  my-mongo:
    type: custom
    image: mongo:7
    backups:
      schedule: daily
      retention: 7
      command: ["mongodump", "--archive=/backup/dump.gz", "--gzip"]
      restore_command: ["mongorestore", "--drop", "--archive=/backup/dump.gz", "--gzip"]

Backup Fields

Validation

• backups is allowed on postgres, redis, and custom services only
• command is required for custom services and not allowed for postgres / redis
• restore_command applies to custom services only
• retention must be between 1 and 365
• Custom cron expressions must have exactly 5 fields

Scoped Databases

By default, all services that reference a database share the same database instance and keyspace. The databases field lets you scope databases so different groups of services get isolated databases.

This is useful when you have multiple logical domains (e.g., an auth service and an analytics service) that should not share a database.

services:
  api:
    type: fastapi
    env:
      DATABASE_URL: ${postgres.url}

  analytics:
    type: custom
    env:
      DATABASE_URL: ${postgres.url}

  postgres:
    type: postgres
    databases:
      main: [api]
      analytics: [analytics]

services:
  postgres:
    type: postgres
    databases: per_service

services:
  api:
    type: fastapi
    env:
      DATABASE_URL: ${postgres.url}

  worker:
    type: custom
    env:
      DATABASE_URL: ${postgres.url}

  postgres:
    type: postgres
    # No "databases" field — api and worker share the same database

Scoped Databases for Redis

Redis scoping works the same way, but uses numbered Redis databases (0-15):

services:
  redis:
    type: redis
    databases:
      cache: [api, frontend]
      sessions: [auth-service]
      queues: [worker]

Validation

• databases is only allowed on postgres and redis services
• Group names must be DNS-safe
• A service that references ${<database>.url} must belong to exactly one group
• A service cannot appear in multiple groups for the same database
• Redis has a maximum of 16 groups

Jobs

Top-level jobs are finite workloads declared outside services. Use them for migrations, setup tasks, asset builds, scheduled reports, maintenance tasks, or manual operations that should not run as long-lived services.

jobs:
  setup:
    image: ghcr.io/acme/setup:latest
    command: ["./setup.sh"]
    run: once

  daily-report:
    build:
      source: ./reports
    command: ["python", "-m", "reports.daily"]
    run: cron
    schedule: daily

  rebuild-search:
    image: ghcr.io/acme/search-tools:latest
    command: ["./rebuild.sh"]
    run: manual

JobSpec Reference

Run Policies

Operate jobs with hostess jobs.

Environments

Environments represent different deployment targets such as production, staging, preview, or a custom stage. In hostess.yml, per-environment configuration is expressed with environments.<env>.domains.

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

  staging:
    domains:
      frontend: [staging.myapp.com]
      api: [api-staging.myapp.com]

Environment Fields

Staging

Staging environments are long-lived environments for pre-production testing:

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

Custom Environments

You can define any custom environment name:

environments:
  qa:
    domains:
      frontend: [qa.myapp.com]
  demo:
    domains:
      frontend: [demo.myapp.com]

Per-Environment Domains

Custom domains can be configured at two levels:

1. Service-level domains — Shorthand for production:

services:
  frontend:
    domains: [myapp.com]   # Applies to production only

2. Environment-level domains — Explicit per-environment:

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

Domain Rules

• Environment-level domains override service-level domains for that environment
• Service-level domains only applies to the production environment
• A domain cannot appear in multiple environments (must be globally unique)
• Service-level and environment-level domains for the same service cannot conflict

Complete Examples

Minimal Example

The simplest possible hostess.yml — a single Next.js app:

version: "1.0"

services:
  app:
    type: nextjs
    build:
      source: .
    domains:
      - myapp.com

Full-Stack Application

A complete e-commerce platform with frontend, backend, database, cache, and background workers:

version: "1.0"
name: E-Commerce Platform
description: Next.js frontend with FastAPI backend

environments:
  production:
    domains:
      frontend: [myorg.com, www.myorg.com]
      backend: [api.myorg.com]

services:
  database:
    type: postgres
    resources:
      preset: large
      storage: 20Gi
    retention: permanent

  cache:
    type: redis
    resources: medium
    retention: permanent

  backend:
    type: fastapi
    build:
      source: ./backend
    env:
      DATABASE_URL: ${database.url}
      REDIS_URL: ${cache.url}
      JWT_SECRET: ${secret:JWT_SECRET}
      STRIPE_KEY: ${secret:STRIPE_KEY}
    depends_on:
      - database
      - cache
    replicas:
      min: 2
      max: 10
      target_cpu: 70
    resources: medium
    lifecycle:
      migrate:
        command: ["alembic", "upgrade", "head"]
    domains:
      - api.myorg.com

  frontend:
    type: nextjs
    build:
      source: ./frontend
    env:
      NEXT_PUBLIC_API_URL: ${backend.external_url}
    depends_on:
      - backend
    replicas:
      min: 2
      max: 20
    resources: medium
    domains:
      - myorg.com
      - www.myorg.com

  worker:
    type: custom
    build:
      source: ./backend
    command: ["celery", "-A", "app.celery", "worker", "--loglevel=info"]
    env:
      DATABASE_URL: ${database.url}
      REDIS_URL: ${cache.url}
    depends_on:
      - database
      - cache
    replicas: 3
    resources: medium

Microservices Architecture

Multiple independent services sharing infrastructure:

version: "1.0"
name: Microservices Platform

services:
  postgres:
    type: postgres

  redis:
    type: redis

  auth-service:
    type: fastapi
    build:
      source: ./services/auth
    env:
      DATABASE_URL: ${postgres.url}
      REDIS_URL: ${redis.url}
      JWT_SECRET: ${secret:JWT_SECRET}
    domains:
      - auth.platform.io

  user-service:
    type: fastapi
    build:
      source: ./services/users
    env:
      DATABASE_URL: ${postgres.url}
      AUTH_URL: ${auth-service.url}
    depends_on:
      - postgres
      - auth-service
    domains:
      - users.platform.io

  order-service:
    type: fastapi
    build:
      source: ./services/orders
    env:
      DATABASE_URL: ${postgres.url}
      USER_SERVICE_URL: ${user-service.url}
    depends_on:
      - postgres
      - user-service
    domains:
      - orders.platform.io

  frontend:
    type: nextjs
    build:
      source: ./frontend
    env:
      NEXT_PUBLIC_AUTH_URL: ${auth-service.external_url}
      NEXT_PUBLIC_USER_URL: ${user-service.external_url}
      NEXT_PUBLIC_ORDER_URL: ${order-service.external_url}
    domains:
      - platform.io

AI/ML Application

An AI image generator with a dedicated ML inference service:

version: "1.0"
name: AI Image Generator

services:
  database:
    type: postgres

  redis:
    type: redis

  api:
    type: fastapi
    build:
      source: ./api
    env:
      DATABASE_URL: ${database.url}
      REDIS_URL: ${redis.url}
      MODEL_SERVICE_URL: ${ml-inference.url}
    domains:
      - api.aiapp.io

  ml-inference:
    type: custom
    build:
      source: ./ml
      dockerfile: Dockerfile.gpu
    env:
      MODEL_PATH: /models/stable-diffusion
    resources:
      cpu: 4.0
      memory: 16Gi
    replicas:
      min: 1
      max: 5

  worker:
    type: custom
    build:
      source: ./worker
    command: ["celery", "-A", "tasks", "worker"]
    env:
      DATABASE_URL: ${database.url}
      REDIS_URL: ${redis.url}
      ML_SERVICE_URL: ${ml-inference.url}
    replicas: 3
    resources: medium

  frontend:
    type: nextjs
    build:
      source: ./frontend
    env:
      NEXT_PUBLIC_API_URL: ${api.external_url}
    domains:
      - aiapp.io

Multi-Port Service

A MinIO object storage service exposing both the API and console ports:

version: "1.0"
name: Object Storage

services:
  minio:
    type: custom
    image: minio/minio
    command: ["server", "/data", "--console-address", ":9001"]
    ports: [9000, 9001]
    env:
      MINIO_CONSOLE_URL: ${minio.port_2.external_url}

Port 1 (9000) is the S3-compatible API. Port 2 (9001) is the web console. Each gets its own URL:

Port 1: https://my-app-minio-quiet-harbor.hostess.run
Port 2: https://my-app-minio-quiet-harbor-2.hostess.run

Appendix: Validation Rules

Service names

• Length: 2–63 characters (see naming rules under Services).
• Reserved (cannot be used as a service name): hostess, default, system

Dependencies

Appendix: Default Values

A quick reference of defaults when fields are omitted:

Default Storage by Preset