Quick start

This page covers the safe core loop. Every command here is read-only or local-file-only. The container runtime stays untouched until you opt into a confirmed lifecycle command at the end.

Requirements

Hostwright targets one environment:

• An Apple silicon Mac (arm64).
• macOS 26 or later.
• Apple container installed and working, for runtime-backed commands.
• Container images that provide a linux/arm64 variant.

Check your host first:

hostwright doctor

doctor runs safe local checks only: OS version, architecture gate, Swift toolchain, whether a container executable is on PATH, manifest presence, and local resource facts. It never runs Apple container commands. See Doctor checks.

The core loop

# 1. Create a starter manifest in the current directory.
#    Never overwrites an existing file; there is no --force.
hostwright init

# 2. Validate the restricted manifest shape. No registry or runtime contact.
hostwright validate

# 3. Compute the deterministic, non-mutating plan.
#    Prints a plan hash, typed issues, and planned actions.
hostwright plan

# 4. Machine-readable output for scripts, if you want it.
hostwright plan --output json

plan does not inspect Apple container by default and does not claim any resource is running or healthy. It is a manifest-level dry run with a deterministic hash. See Reconciliation.

A minimal manifest

The checked-in example at examples/single-service/hostwright.yaml:

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

Every field is described in the hostwright.yaml reference.

Observing the runtime

State-backed commands use a state database resolved from --state-db, then HOSTWRIGHT_STATE_DB, then the default at ~/Library/Application Support/Hostwright/state/state.sqlite. Use the default, or pass an explicit path:

hostwright status
hostwright logs web --state-db /tmp/hostwright.sqlite

status observes Apple container through the RuntimeAdapter, persists a status event and snapshot, and renders desired services against observed facts. It does not mutate anything. Run hostwright paths to see the resolved location.

Mutation is a separate, gated step

The mutating paths

Runtime mutation happens only through a confirmed lifecycle command (hostwright up --confirm-plan <hash>, and its siblings down, run, start, stop, restart, rm, update, plus apply as the same gate under its earlier name) or hostwright cleanup --confirm-cleanup <token>. Each refuses to run if its hash or token does not match currently observed reality.

hostwright image pull docker.io/library/nginx:1.27 --platform linux/arm64 --runtime-provider apple-cli
hostwright up --dry-run --runtime-provider apple-cli
hostwright up --confirm-plan <hash-from-the-dry-run> --runtime-provider apple-cli
hostwright status

The full flow is covered step by step in Plan a single service, and the safety reasoning in the Safety model.

Next

• Desired state: the model behind the manifest.
• Operations and recovery: status, logs, events, diagnostics, cleanup.
• Limitations: what to expect, stated plainly.