hostwright.yaml reference

The manifest filename is hostwright.yaml. A JSON Schema is checked in at schemas/hostwright-yaml.schema.json in the core repository.

Current shape

version: 2
project: api-local
imagePolicy: allow-tags

services:
  api:
    image: ghcr.io/example/api:latest
    ports:
      - "8080:8080"
    env:
      APP_ENV: development
    secretEnv:
      API_TOKEN: keychain://hostwright.api/api-token
    health:
      command: ["curl", "-f", "http://localhost:8080/health"]
      interval: 10s
    restart:
      policy: on-failure

Canonical Hostwright manifests use this contract. Phase 12 translates supported Kubernetes resources rather than overloading this file with Kubernetes apiVersion, kind, or metadata fields.

Version policy

version: 2 is required for execution. Versionless and explicit v1 manifests are legacy input. Preview a deterministic non-writing conversion with hostwright migrate preview hostwright.yaml (or --json). The current preview inserts/replaces the version contract and is idempotent for v2; Phase 04 owns complete semantic migration. Future versions fail closed and Hostwright never silently downgrades input.

Fields

Field	Form	Rules
version	required scalar	Exactly 2.
project	scalar	Required, DNS-like name.
imagePolicy	optional scalar	allow-tags (default) or require-digest.
services.<name>	map	Service names are DNS-like; two-space indentation.
image	scalar	Required per service. No whitespace, must not begin with -; digests must be @sha256:<64 lowercase hex>.
command	inline array	Tokens non-empty and must not begin with -.
ports	string list	"host:container", values 1–65535.
env	string map	Keys shell-safe ([A-Za-z_][A-Za-z0-9_]*). Plaintext credential-like keys are rejected — use secretEnv.
secretEnv	string map	Values must be keychain://<service>/<account>. A key cannot appear in both env and secretEnv.
volumes	string list	`source:/absolute/container/path[:ro
health.command	inline array	Non-empty when health is present. Bounded probe shapes only (see below).
health.interval	scalar	Seconds form, like 10s.
restart.policy	scalar	no, on-failure, or unless-stopped.

Parser limitation

Not a general YAML parser

Hostwright uses a restricted manifest subset parser. Unsupported YAML features fail closed: anchors, aliases, tags, merge keys, block scalars, document markers, flow maps, tabs, and arbitrary indentation. Unsupported orchestrator fields fail closed too, including apiVersion, kind, metadata, build, depends_on, deploy, networks, network_mode, dns, hostname, extra_hosts, aliases, expose, configs, and secrets.

hostwright import-stack can convert a smaller stack-file subset into this shape — conversion only, with the normal validator run on the output.

Image policy

imagePolicy is a local string policy only. The default allow-tags accepts tag-based references. require-digest rejects mutable tag-only references and requires digest pinning:

imagePolicy: require-digest

services:
  api:
    image: ghcr.io/example/api@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

Hostwright does not verify a digest exists in a registry, resolve tags, pull images, verify signatures or SBOMs, or scan vulnerabilities.

Health probes are bounded, not shell

Health checks are not shell commands and are not container exec, and Hostwright does not execute host curl or wget binaries. Current bounded probes parse curl, wget, true, and false shaped commands:

• curl: no-output status flags plus one loopback HTTP(S) URL;
• wget: quiet spider mode plus one loopback HTTP(S) URL;
• true / false: no arguments, evaluated directly.

URL-shaped probes run through Hostwright’s in-process URL fetcher in the daemon.

Ports and networking

The currently executable v2 subset has no bind-address field. Hostwright-created runtime port publishes default to 127.0.0.1. DNS, service discovery, network aliases, and reverse proxy settings are not manifest features.

Untrusted manifests

Treat third-party manifests as untrusted input. validate and plan are non-mutating gates, but an accepted manifest still describes images, ports, environment values, paths, and probe commands an operator should review before any confirmed apply or daemon run.

Never place plaintext credentials in manifests. secretEnv stores a local reference, not a value; see Secrets and Keychain.