hostwright.yaml

The manifest format — the fields shown in the example, what they mean, and what is still under design.

A stack is declared in a single hostwright.yaml file. This page documents the fields used in the example below. Anything not listed here is still under design and should not be relied on.

Annotated hostwright.yaml showing project, services, image, ports, env, health, and restart fields. — The fields documented on this page, called out on a sample manifest.

Example

project: api-local

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

  redis:
    image: redis:7
    ports:
      - "6379:6379"

Fields

Field	Type	Meaning
`project`	string	Name of the project. Scopes ownership and the resources in this stack.
`services`	map	One entry per service, keyed by service name.
`services.<name>.image`	string	The container image reference to run.
`services.<name>.ports`	list of strings	Port mappings in `"host:container"` form.
`services.<name>.env`	map	Environment variables passed to the service.
`services.<name>.health.command`	list of strings	Command run to check health (argv form).
`services.<name>.health.interval`	duration	How often the health command runs, e.g. `10s`.
`services.<name>.restart.policy`	string	Restart behavior. `on-failure` is shown above.

Notes

Images should provide linux/arm64. On Apple silicon, an image that only resolves to amd64 runs under Rosetta and is allowed only by explicit policy.
Health checks are honest about the runtime: a check can only report what Apple container can observe.

Open questions

The canonical duration format and which fields accept durations.
Whether the manifest gains an explicit schema version field before the first release.
How secret and config references are expressed without ever putting secrets in the file. See the safety model.