Quick Start

Install the CLI

If you haven't already, install the Hostess CLI:

curl -fsSL https://hostess.sh/install.sh | sh

Verify the installation:

hostess --version

hostess version 0.1.x

Your output may show a different version until you reinstall from the latest release via the install script.

Log in to your account

Authenticate with your Hostess account:

hostess login

hostess login runs an interactive flow in the terminal (not a browser). The flow is always email → OTP:

Login to Hostess

Enter your email address:
you@example.com

If the email is new, Hostess asks for first name and last name before sending the code. Then:

Check your email!

Enter code:
482901

✓ Logged in as you@example.com

Use ↑/↓, Enter, Esc as indicated in each screen. Press r on the code step to resend the OTP.

Create your project directory

If you already have a Next.js app, navigate to its root directory. Otherwise, create a new one:

npx create-next-app@latest my-app
cd my-app

Your project directory should look something like this:

my-app/
├── app/
│   ├── layout.tsx
│   └── page.tsx
├── package.json
├── Dockerfile
├── next.config.ts
└── ...

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

EXPOSE 3000
CMD ["node", "server.js"]

Write your hostess.yml

Create a hostess.yml file in the root of your project. This file tells Hostess what services to deploy and how they connect:

version: "1.0"
name: my-app

services:
  web:
    type: nextjs
    build:
      source: .
    env:
      DATABASE_URL: ${database.url}
    depends_on:
      - database

  database:
    type: postgres
    resources: small

This configuration defines two services:

• web — Your Next.js application, built from the current directory. It receives a DATABASE_URL environment variable that automatically points to the Postgres database.
• database — A managed PostgreSQL database with the small resource preset (0.5 CPU, 512Mi memory, 10Gi storage).

The depends_on field ensures the database is healthy before the web service starts. The magic variable ${database.url} is resolved automatically at deploy time with the full database connection string, including the password.

Deploy

Run the deploy command from your project directory:

hostess deploy

If the project name from hostess.yml does not exist yet, the CLI prompts you to pick an organization (project name is already known from the file — there is no separate “project name” prompt):

Project not found

Project 'my-app' does not exist. Create it in which organization?

▸ Acme (acme)
  Personal (personal)

↑/↓ to select, Enter to confirm, Esc to cancel

After you confirm, a line like this is printed before the deploy UI runs:

✓ Project 'my-app' created in organization 'acme'

While the deployment runs, the CLI shows a five-step progress view (wording and sub-lines update as the API reports build/service state). It looks conceptually like this:

Deploying project: my-app
Environment: preview
Services: database, web

[1/5] Validating config... done
[2/5] Creating deployment... done (dep_abc123)
[3/5] Building images...
  - web: built
[4/5] Starting services...
  - database: ready
  - web: ready
[5/5] Finalizing... done

When everything succeeds, the same header is shown again with a short summary (IDs and URLs are examples):

Deploying project: my-app
Environment: preview
Services: database, web

Deployment complete
Deployment ID: dep_abc123

web: https://my-app-web-k7xm9p2q.hostess.run
database: connection info available via `hostess inspect dep_abc123`

→ View deployment: https://hostess.sh/dashboard/org/acme/projects/prj_xyz/deployments/dep_abc123

For private database services, the completion screen points at hostess inspect with that deployment id for connection details. You can still run hostess connect database or hostess ps to work with the service.

If you added custom domains that are still pending DNS verification, the CLI may print Custom domain DNS records: with CNAME lines after a successful deploy.

Visit your application

Open the URL from the deploy output in your browser:

open https://my-app-web-k7xm9p2q.hostess.run

Your Next.js application is live, connected to a fully managed PostgreSQL database, with automatic HTTPS.

View in Studio

The Hostess Studio is a web dashboard where you can monitor your deployments, view logs, manage services, and more. Visit:

https://hostess.sh

In Studio, you will see:

• Your project with its services listed
• Deployment status and history
• Service details including URLs, resource usage, and logs
• Database dashboards with connection info and metrics

You can also view your deployment from the CLI:

hostess ps

hostess ps is an alias for hostess services list. The table includes a PORTS column; ready services show status Running (not “healthy”):

SERVICE          TYPE       STATUS     PORTS    URL
────────────────────────────────────────────────────────────────────────────────
web              nextjs     Running    3000     https://my-app-web-k7xm9p2q.hostess.run
database         postgres   Running    5432     hostess connect database