hostess deploy

Description

Deploy your application to Hostess. By default, hostess deploy reads hostess.yml and deploys its services. Use a path or --type for one FastAPI, Next.js, or static app. See Deploy without hostess.yml.

For a new project, Hostess can prompt you to create it interactively and select an organization.

The deploy command handles the entire deployment lifecycle:

1. Reads hostess.yml or creates a one-service config from a path or --type
2. Authenticates with the Hostess API
3. Creates a new project in interactive mode when needed
4. Uploads your source code
5. Builds container images
6. Deploys services in dependency order
7. Shows real-time progress in an interactive TUI

Usage

hostess deploy [path] [flags]

Flags

Examples

Deploy from the current directory

The most common usage. Reads hostess.yml from the current directory:

hostess deploy

Deploying my-app (preview)
Services: api, database, frontend

Deployment ID: dep_abc123
Status: building
Status: starting services
Service database: ready
Service api: ready
Service frontend: ready
Status: complete

✓ Deployment complete (dep_abc123)
api: https://my-app-api-calm-brook.hostess.run
frontend: https://my-app-frontend-able-arc.hostess.run

→ View deployment: https://hostess.sh/dashboard/org/my-org/projects/proj_abc123/deployments/dep_abc123

Deploy a folder or HTML file

Quick mode creates one service. Set --project. The service name is web unless you set --name.

hostess deploy --type fastapi --project my-api
hostess deploy ./api --type fastapi --project my-api
hostess deploy ./web --type nextjs --project my-web
hostess deploy ./artifact --type static --project my-demo
hostess deploy ./page.html --project my-page

Without a path, --type uses the current directory (.). Hostess infers static for an .html file. For a directory, it checks Next.js dependencies, FastAPI manifests, or index.html. If it cannot infer the type, set --type.

hostess deploy ./api --type fastapi --project my-api --public --port 8080
hostess deploy ./site --type static --project my-demo --spa --output dist

--print-config prints YAML to stdout and detection notes to stderr, then exits. It does not authenticate or use the network. --save writes hostess.yml in the target directory or beside an HTML file, then deploys. It does not overwrite an existing file. Without --save, quick mode warns when hostess.yml exists and deploys the generated config.

hostess deploy ./api --type fastapi --project my-api --print-config
hostess deploy ./api --type fastapi --project my-api --save

See Deploy without hostess.yml.

Deploy from a specific config file

hostess deploy -f ../other-project/hostess.yml

Deploy from a GitHub repository

Deploy image-only services (no build step) directly from a GitHub repository:

hostess deploy -r myorg/myproject

Deploy selected services only

When you only want to update specific services without redeploying everything:

hostess deploy -s api -s web

This is useful for large stacks where you've only changed one or two services. Unchanged services remain running at their current version.

Deploy to a specific environment

hostess deploy --env staging

Override the project name

hostess deploy --project my-other-project

CI/CD usage with token

In CI/CD pipelines where interactive prompts aren't available:

hostess deploy --token $HOSTESS_TOKEN --no-interactive

Or using an environment variable:

export HOSTESS_TOKEN="pat_abc123..."
hostess deploy --no-interactive

Full CI/CD example

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Hostess CLI
        uses: howl-cloud/setup-hostess@v1

      - name: Deploy
        run: hostess deploy --no-interactive --env production
        env:
          HOSTESS_TOKEN: ${{ secrets.HOSTESS_TOKEN }}

Deployment Flow

When you run hostess deploy, the following happens:

1. Configuration loading — The CLI reads and validates hostess.yml or creates a one-service config from a path or --type
2. Authentication — Resolves your token from --token flag, HOSTESS_TOKEN env var, or saved login
3. Project resolution — Finds your project by name, or prompts to create one
4. Environment selection — Uses --env or defaults to production
5. Source upload — Archives and uploads your source code (for services with build: configs)
6. Build — Hostess builds container images for each service
7. Deploy — Services are deployed in dependency order
8. Health checks — Hostess waits for all services to pass health checks
9. URL assignment — Each public service gets a hostess.run URL

Interactive vs Non-Interactive

In an interactive terminal (TTY), the deploy command shows a rich TUI with real-time status updates for each service. In non-interactive mode (CI/CD, piped output), it shows a simpler text output with deployment ID and final status.

If the project is new in interactive mode, Hostess prompts you to create it and select an organization. In non-interactive mode (--no-interactive), create the project first with hostess projects create <name>. If the target environment does not exist, an interactive deploy offers to create it; with --no-interactive, the CLI prints an exact hostess environments ensure <name> ... command to run first.

Build Logs

Build output streams live while each service builds — you see your own build steps as they happen:

── Build: api ──
→ Preparing
→ Pulling base image
→ Installing
   added 214 packages in 6s
→ Building
→ Pushing image

This works in both the interactive TUI and non-interactive output, and the same live logs appear on the build's page in Studio.

If a build fails, the deploy stops and the failing service's output is shown with a short, actionable summary of what went wrong. You can re-open a build's full logs anytime from Studio.

Cancellation

You can cancel a running deployment by pressing Ctrl+C. Hostess will send a cancellation request to the API and clean up any in-progress resources.