Documentation menu

Getting started

What you need to run Hostwright, and the shape of the core workflow — declare, validate, plan, apply.

This page describes how Hostwright is meant to be used. It is written against the design, so you can see the intended workflow before the implementation lands.

Requirements

Hostwright targets one environment deeply rather than many shallowly:

  • An Apple silicon Mac (arm64).
  • macOS 26 or later. Earlier macOS versions are out of scope for the first release because of Apple container networking limitations.
  • Apple container installed and working, with its system services available.
  • Container images that provide a linux/arm64 variant. amd64/Rosetta is allowed only by explicit manifest policy.

You can confirm most of this with hostwright doctor, which reports what is present, what is missing, and what is unsupported.

The core loop

The everyday workflow is small and predictable:

# 1. Create a manifest and project metadata in the current directory.
hostwright init

# 2. Check the manifest against the schema and semantic rules.
hostwright validate

# 3. See exactly what would change in the runtime — no mutation.
hostwright plan

# 4. Verify the host is ready.
hostwright doctor

Once you are satisfied with the plan, you apply it and observe the result:

hostwright apply        # converge runtime state to the manifest
hostwright status       # desired vs actual, health, drift, restarts
hostwright down --dry-run   # preview teardown before removing anything

plan before apply, and --dry-run before any destructive command, are the defaults Hostwright is built around. See the safety model.

A minimal manifest

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"

Every field here is described in the hostwright.yaml reference.

Next