Desired-state container control for Apple silicon Macs.
Hostwright is a Mac-native control plane for Apple container workloads. Today it can initialize, validate, plan without mutation, show manifest-level status, and run safe doctor checks while the runtime control loop is built.
The problem
Apple container is a runtime. Local stacks still need a control plane.
Apple container gives the Mac a real, native container runtime surface — lightweight Linux VMs, an OCI image flow, and a command surface built for Apple silicon.
But running a local multi-service stack is more than starting containers. You still need declared state, validation, health checks, restart policy, drift detection between what you asked for and what is actually running, and cleanup you can trust.
Hostwright is the disciplined layer that sits above the runtime and owns that responsibility on a single Mac.
What it does
What Hostwright does
A narrow, well-defined release direction: declare a stack, see the plan, then later converge to it through a single runtime boundary.
-
Declares services in hostwright.yaml
A readable manifest describes the local stack you want to exist.
-
Plans changes before mutation
The current plan command is non-mutating and manifest-level. Runtime action planning comes after observation exists.
-
Routes operations through a RuntimeAdapter
The boundary exists now. Real runtime calls are planned and must cross this typed boundary.
-
Tracks local state
Durable desired state, events, and ownership are planned for the SQLite phase.
-
Detects drift
Drift detection is planned after read-only runtime observation exists.
-
Runs doctor checks
Runs safe local checks for OS, architecture, Swift, manifest presence, and `container` executable lookup.
-
Treats destruction as explicit
Cleanup and teardown are not implemented yet; the release design requires dry-run and ownership checks first.
Scope
What it deliberately does not do yet
Stated openly. A narrow, defensible first release matters more than a broad one.
-
Not a CRI shim
The Container Runtime Interface is studied as design inspiration for the adapter boundary, not implemented.
-
Not a Kubernetes replacement
No scheduler, no API server, no kubelet. Single-host desired state, not cluster orchestration.
-
Not full Docker Compose parity
A readable local stack format, deliberately narrower than Compose — not a drop-in clone.
-
Not a Docker API shim
Existing projects already cover Docker API emulation. Hostwright stays controller-first.
-
Not a cloud control plane
No remote control plane, no multi-Mac orchestration, no hosted service.
-
Not a tunnel manager
No tunnels, no DNS service, no Cloudflare, Tailscale, or WireGuard integration. Research-only.
-
Not a GPU scheduler
No Apple GPU/ANE scheduling and no Metal, Core ML, or MLX container support. Research-only.
-
Not production-ready
This is an early infrastructure project under active design. Do not depend on it for production work.
Command line
A small, honest CLI
hostwright init
hostwright validate
hostwright plan
hostwright status
hostwright doctorhostwright apply
hostwright down --dry-runThe command surface is still in design. These are the intended shapes, not a shipped tool — commands marked Planned are not implemented yet.
Architecture
Architecture
Hostwright currently owns manifest parsing, validation, non-mutating planning, and architecture boundaries. Apple container owns the runtime. The RuntimeAdapter is the boundary future runtime behavior must cross.
Manifest
Declare a stack in one file
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"Safety
Safety model
Infrastructure tooling earns trust by being predictable under failure. Hostwright's defaults are conservative.
-
Plan before mutation
Runtime changes are computed and reviewable before they run.
-
Dry-run for cleanup
Cleanup is planned to preview exactly what it would remove before it can remove anything.
-
Explicit destructive confirmation
Removing real resources requires an intentional, confirmed action.
-
Conservative validation
Unsafe or ambiguous manifests are refused, not guessed at.
-
No hidden runtime mutation
Current commands do not mutate runtime state. Future mutation must use the planned, recorded path.
-
Ownership-tracked cleanup
Cleanup is planned to touch only resources Hostwright can prove it owns.
-
No secret leakage in logs
Secrets and credentials are kept out of events and log output.
Current state
Roadmap
Honest status. The design is locked; the build is just beginning.
- Design locked Implemented
Architecture, boundaries, and the first-release contract are written down.
- Repo scaffold Planned
Swift package layout, module boundaries, tests, CI, and decision records.
- CLI skeleton Planned
Argument parsing and command dispatch for the hostwright command surface.
- Manifest validation Planned
Schema and semantic checks for hostwright.yaml before any runtime action.
- RuntimeAdapter Planned
The typed runtime boundary plus a mock adapter for testing the reconciler.
- Apple container adapter Planned
First concrete adapter over the Apple container CLI with structured output.
- Reconciler Planned
Observe, diff, plan, apply, observe — idempotent and deterministic.
- State store Planned
Durable desired state, events, and ownership ledger in SQLite.
- Doctor checks Planned
Host, macOS, architecture, and Apple container readiness diagnostics.
- Safe cleanup Planned
Ownership-aware teardown with dry-run and explicit destructive confirmation.