Plan a single service

Validate and plan are read-only. The optional apply at the end is mutating and requires its own explicit gates.

The example manifest

examples/single-service/hostwright.yaml in the core repository:

version: 2
project: single-service

services:
  web:
    image: docker.io/library/nginx:1.27
    ports:
      - "8080:80"
    health:
      command: ["curl", "-f", "http://localhost:8080/"]
      interval: 30s
    restart:
      policy: on-failure

1. Validate

hostwright validate examples/single-service/hostwright.yaml

Validation checks the restricted manifest shape only. It does not contact registries, does not contact Apple container, and does not check whether the image exists anywhere.

2. Plan

hostwright plan examples/single-service/hostwright.yaml --output json

The output contains a deterministic planHash, typed issues, typed actions, and observationConnected: false — plan does not inspect Apple container by default and does not claim anything is running, stopped, healthy, or unhealthy. Running it twice on the same manifest produces the same hash.

3. Apply — separate, explicit, gated

Mutating step

Apply is not a continuation of plan — it is its own command with its own requirements: an explicit state database path, a matching plan hash recomputed against a live runtime observation, and a locally present image.

hostwright apply examples/single-service/hostwright.yaml \
  --state-db /tmp/hostwright.sqlite \
  --confirm-plan <hash-from-the-observed-plan>

Apply validates the manifest, observes Apple container, recomputes the plan, and refuses if your hash does not match the observed plan. It persists desired state, observed state, operation intent, and an apply-start event before mutation, then executes exactly one action — here, creating the missing web service with its port published to 127.0.0.1:8080. Success or failure lands in the event ledger.

If the local image is missing, apply refuses before mutation — Hostwright never pulls images. Fetch it yourself first (for example container image pull docker.io/library/nginx:1.27) and re-plan.

Next

• Review an app suite — the same flow with multiple services.
• Safety model — every refusal condition of the apply gate.
• Limitations — what apply cannot do (multi-action, rollback, image replacement).