Using an AI assistant

Hostwright’s command surface and manifest format have grown quickly. Assistants trained on an earlier snapshot, or on generic container-tooling conventions, tend to guess wrong in both directions: inventing flags that never existed, or asserting a command “doesn’t exist yet” after it shipped. This page is one prompt that fixes both, kept in sync with the current CLI and manifest reference.

The prompt

Paste this into your assistant before asking it to help with Hostwright:

I want to try Hostwright, a Mac-native desired-state container platform for
Apple silicon, in active development. Use only the commands and manifest
fields below; do not invent flags, and do not assume Docker Compose or
Kubernetes semantics apply.

Install: `brew install hostwright/tap/hostwright` (a vendor-tap qualification
build), or build from source:
  git clone https://github.com/hostwright/hostwright
  cd hostwright && swift build && swift test
In a source checkout, run commands as `swift run hostwright ...`.

Safe commands (no runtime mutation): --version, capabilities, runtime
providers, paths, state integrity, migrate preview, init, import-stack,
validate, plan, status, logs, events, recovery, diagnostics, cleanup
--dry-run, every lifecycle command with --dry-run, doctor. State-backed
commands resolve their database from --state-db, then HOSTWRIGHT_STATE_DB,
then the default at ~/Library/Application Support/Hostwright/state/state.sqlite.

Mutation happens ONLY through an explicit --confirm-plan <hash> (lifecycle:
up, down, run, start, stop, restart, rm, update, plus apply as a compatibility
alias for a confirmed up plan) or --confirm-cleanup <token> (cleanup), plus
narrower confirmed gates for image prune, volume delete/prune, secret
create/update/delete, and registry/runtime-provider operations. I want to run
every confirmed command myself. Never suggest running one automatically, and
never invent a command or flag not listed here.

The manifest (hostwright.yaml, version: 2) supports per project: project,
imagePolicy (allow-tags|require-digest), and a top-level volumes: map. Per
service: image, replicas, platform, resources, user, group, workdir,
entrypoint, command, init, dependsOn, ports, volumes (typed bind/volume/
tmpfs), env, secretEnv (keychain://, env-file://, local-file://, external://,
or plugin:// references, never a literal secret value), labels, probes
(startup/readiness/liveness, each exec/http/tcp), restart.policy, update,
hooks, readOnlyRootFilesystem, shmSize, rosetta, virtualization. Do not add
Kubernetes apiVersion/kind/metadata or Compose build/depends_on/deploy/
networks fields; the parser fails closed on them. Custom networks and DNS are
not yet part of the executable manifest.

Help me: install or build it, run doctor, generate a starter manifest with
init, then validate and plan it.

Why this exists

An assistant’s default instincts (assume a mature-looking project has a package-manager entry, assume every “plan” implies an unconditional “apply”, assume a small early command surface is still small) are each wrong somewhere in Hostwright’s current surface. The prompt is the same ground truth documented on this site, handed to the assistant before it guesses. The authoritative surfaces are the CLI reference and the manifest reference; when this page and those disagree, the reference pages win.

If an agent works inside your repository

Drop the same constraints into a rules file the agent reads automatically: AGENTS.md or CLAUDE.md at your repo root:

# Hostwright agent ground rules

Install via `brew install hostwright/tap/hostwright` or build from source and
run via `swift run hostwright ...`. Safe commands: --version, capabilities,
runtime providers, paths, migrate preview, init, import-stack, validate,
plan, status, logs, events, recovery, diagnostics, cleanup --dry-run, every
lifecycle command with --dry-run, doctor. Stateful commands need an explicit
--state-db path or HOSTWRIGHT_STATE_DB.

Mutation only via an explicit --confirm-plan <hash> (up/down/run/start/stop/
restart/rm/update, or apply as a compatibility alias for up) or
--confirm-cleanup <token> (cleanup), plus narrower gates for image prune,
volume delete/prune, and secret/registry operations. Never run a confirmed
command without asking me first, and never invent flags.

hostwright.yaml (version: 2) supports project, imagePolicy, top-level
volumes:, and per service: image, replicas, platform, resources, user,
group, workdir, entrypoint, command, init, dependsOn, ports, typed volumes,
env, secretEnv (typed references only), labels, probes, restart.policy,
update, hooks, readOnlyRootFilesystem, shmSize, rosetta, virtualization. No
Kubernetes or Compose fields. No custom networks or DNS yet.