Desired state
Hostwright separates the state you declare from the state that is actually running, and works to close the gap.
Hostwright is a desired-state system. You do not start and stop containers by hand. You declare the state you want the machine to be in, and Hostwright is responsible for making the running system match it — and for telling you when it does not.
Two kinds of state
- Desired state — what you declared in
hostwright.yaml. It is persisted durably so it survives daemon restarts and machine reboots. - Observed state — what is actually running, read back from the runtime through the RuntimeAdapter at a point in time.
The job of the reconciler is to compare the two, compute the difference, and converge observed state toward desired state.
Why declare instead of command
Imperative commands describe how; a manifest describes what. A declarative model gives you properties that are hard to get from a pile of shell commands:
- Idempotency — applying the same manifest twice converges to the same result.
- Drift detection — because the desired state is recorded, Hostwright can notice when reality has diverged from it.
- Reviewable change — the difference between current and desired state can be shown as a plan before anything mutates.
- Recovery — desired state is not lost when the daemon restarts.
The unit of declaration
A manifest declares a project that contains one or more services. A service references an image and the runtime details needed to run it — ports, environment, health checks, and restart policy.
project: api-local
services:
api:
image: ghcr.io/example/api:latest
ports:
- "8080:8080"Open questions
- Rollback. When an apply fails partway, should Hostwright roll back automatically, or stop and hand you an explicit recovery plan? The current stance is conservative: automatic rollback only when every affected resource is owned by Hostwright and the rollback is deterministic. See the safety model.
- Replicas. Running more than one instance of a service interacts with Apple container’s VM-per-container model. The scheduling and naming details for replicas are still under design.