HostStack Docs

Infrastructure as Code

Declare your service's runtime, build, env, scaling, and disk shape in a hoststack.yaml committed alongside your code. The agent reads the same schema on every deploy, so the file is the single source of truth for how a service runs.

Quick Start

hoststack.yaml

# Lives at the repository root. Auto-detected on first deploy.
services:
  web:
    type: web_service
    runtime: bun
    build:
      command: bun install && bun run build
    start:
      command: bun run start
    healthCheck:
      path: /health
      interval: 30
      timeout: 5
    scaling:
      min: 1
      max: 4
    disk:
      name: data
      mountPath: /var/data
      sizeGB: 10
    env:
      NODE_ENV: production

Run hoststack init to drop a template in your repo, then hoststack validate to type-check the YAML against the same Zod schema the API uses.

How the file is applied

HostStack reads hoststack.yaml from the repository on every deploy. Fields the file declares — runtime, build/start commands, health-check path, scaling bounds, disk shape, env keys — overwrite the service's stored config for that deploy. Fields the file omits keep their dashboard values, so you can layer YAML over a service created in the UI without losing settings.

Env vars are additive: keys in the YAML are merged with keys set in the dashboard, with the dashboard winning on conflicts. Mark a key as a secret in the dashboard and the YAML must not provide a value — the agent reads the secret from the encrypted store at deploy time.

Validation in CI

Fail the build before you push by running the CLI's validator in your CI step. It catches typos, unknown keys, and schema-rule violations (e.g. scaling.min > max):

bash

# In any CI runner with Node 20+ or Bun
npm install -g @hoststack.dev/cli
hoststack validate         # exits 0 on success, 1 on schema error

hoststack validate does not call the HostStack API and does not need an API key — it's a pure local schema check.

Programmatic provisioning

HostStack does not run a server-side reconciler — there is no terraform apply equivalent that diffs the YAML against your team and creates missing services. Use the TypeScript SDK or the CLI to create projects / services / databases / env vars programmatically; once the service exists, its hoststack.yaml takes over on each deploy.

AI agents (Claude, Cursor) can use the MCP server to spin up the surrounding resources in one shot — a single prompt creates the project, service, database, and env vars, then commits the matching hoststack.yaml to your repo.

Schema reference

The complete schema lives in the open-source @hoststack/shared package (schemas/hoststack-yaml.ts). Top-level keys:

services — map of name → config. Each name becomes the service's display name and its in-cluster DNS alias.
services.<name>.type — one of web_service, private_service, worker, cron_job, static_site.
services.<name>.build — command, multistage (Bun/Node only).
services.<name>.start — command for web / worker / cron services.
services.<name>.healthCheck — path, interval, timeout (seconds). Startup grace and thresholds are configured per service in the dashboard.
services.<name>.scaling — min, max (autoscale thresholds are configured in the dashboard).
services.<name>.disk — name, mountPath, sizeGB (1–100).
services.<name>.env — map of { KEY: value } entries. Omit values for keys that should read from the encrypted secret store.
databases — map of name → config with engine, optional version and plan.

Next: Deploying Your First App · CLI Reference