Quick start

This guide uses the CLI development build. Validation and planning are non-mutating. Starting or stopping workloads changes local runtime state and requires explicit plan confirmation.

Requirements

Apple silicon and macOS 26 or later;
a Hostwright source build or the unsupported vendor-tap qualification build;
Apple container for live runtime commands;
an available Linux ARM64 image.

Declare a workload

Save this as hostwright.yaml:

version: 3
project: quickstart
imagePolicy: require-digest

services:
  web:
    image: docker.io/library/python@sha256:26730869004e2b9c4b9ad09cab8625e81d256d1ce97e72df5520e806b1709f92
    resources:
      requests:
        cpus: 1
        memory: 512MiB
      limits:
        cpus: 1
        memory: 512MiB
    command: ["python3", "-m", "http.server", "8080", "--bind", "0.0.0.0"]
    ports:
      - "18080:8080"
    restart:
      policy: unless-stopped

Inspect the installed provider and validate the file:

hostwright runtime providers --json
hostwright validate hostwright.yaml

Pull the image and inspect the plan without changing the runtime:

hostwright image pull \
  docker.io/library/python@sha256:26730869004e2b9c4b9ad09cab8625e81d256d1ce97e72df5520e806b1709f92 \
  --platform linux/arm64 --runtime-provider apple-cli
hostwright up hostwright.yaml --dry-run --runtime-provider apple-cli

Confirm a lifecycle action

Review the complete plan and its image, resource, and port details. If it is correct, copy its plan hash into the confirmed command:

hostwright up hostwright.yaml \
  --confirm-plan <plan-hash> --runtime-provider apple-cli
hostwright status hostwright.yaml --runtime-provider apple-cli

Confirmed operations use the authenticated local daemon. Missing, stale, or unauthorized authority fails closed. Repeat the dry-run and confirmation flow for down; each new plan requires its own current hash.

For every field and rejection rule, see the Manifest reference and the core quick start.