Quick start

This quickstart requires a signed current-source candidate on one Apple silicon Mac running macOS 26. The public tap still installs dev.12, which uses older commands and contracts. Current-candidate live qualification is pending; see installation and compatibility.

Prepare

Start Apple container, then save the canonical single-service example below to a new hostwright.yaml. First check that its project and host port do not conflict with an existing workload. Create this file before starting the daemon; CLI validation, planning, and runtime requests use the authenticated Control API.

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"
    probes:
      startup:
        exec: ["python3", "-c", "raise SystemExit(0)"]
      readiness:
        tcp:
          port: 8080
      liveness:
        http:
          port: 8080
          path: /
    restart:
      policy: unless-stopped
    update:
      strategy: recreate
      maxSurge: 0
      maxUnavailable: 1
      progressDeadline: 60s

In a separate terminal under the same macOS account, change to the directory containing hostwright.yaml, bootstrap the installed identities and start the foreground daemon:

hostwright daemon bootstrap-identities --json
hostwrightd --foreground --config "$PWD/hostwright.yaml"

Keep that terminal running while using the CLI. See daemon setup for managed service installation and local path requirements.

Review and execute

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

validate and plan do not change the runtime. plan is a manifest-level plan; the lifecycle confirmation hash comes from the observed-runtime up --dry-run. Review its exact image, resource requests/limits, ownership, provider, and actions.

Confirmed execution requires the signed payload and an authenticated local daemon identity. Follow the installation guide and daemon reference. An absent or stale authority fails closed.

hostwright up hostwright.yaml --confirm-plan <planSHA256> --runtime-provider apple-cli
hostwright status hostwright.yaml --runtime-provider apple-cli --output json
curl --fail http://127.0.0.1:18080/

Use the exact hash from the fresh dry run, with the same manifest, provider, and selected state path. If anything changes, review another dry run. Stopping and removing resources each require their own fresh dry-run hash:

hostwright down hostwright.yaml --dry-run --runtime-provider apple-cli
hostwright down hostwright.yaml --confirm-plan <down-planSHA256> --runtime-provider apple-cli
hostwright rm hostwright.yaml --dry-run --runtime-provider apple-cli
hostwright rm hostwright.yaml --confirm-plan <rm-planSHA256> --runtime-provider apple-cli

Only proven Hostwright-owned resources are eligible for removal. Preserve unmanaged workloads and inspect recovery after interruption. Press Control-C in the foreground daemon terminal after cleanup if you started it for this walkthrough.

The desktop quickstart covers manifest selection, confirmed Start/Stop actions, logs and CLI removal using the same signed installation.