Desired-state container control for Apple silicon Macs.
Hostwright is a Mac-native control plane for Apple container workloads. Define a local stack once, inspect the plan, and let a local reconciler keep runtime state honest.
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 contract: declare a stack, see the plan, converge to it, and observe the result.
-
Declares services in hostwright.yaml
A readable manifest describes the local stack you want to exist.
-
Plans changes before mutation
Every runtime change is computed and shown before anything is applied.
-
Routes operations through a RuntimeAdapter
All runtime calls cross one typed boundary, never ad-hoc shell commands.
-
Tracks local state
Desired state, events, and resource ownership are recorded durably.
-
Detects drift
Compares declared state against observed runtime state and reports the difference.
-
Runs doctor checks
Validates Apple container, macOS, architecture, and runtime assumptions up front.
-
Treats destruction as explicit
Cleanup and teardown are deliberate operations, never silent side effects.
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 doctorhostwright apply
hostwright status
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 owns declared state, planning, reconciliation, health, drift, events, and cleanup policy. Apple container owns the runtime. The RuntimeAdapter is the boundary between them.
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
Destructive operations preview exactly what they would remove first.
-
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
Nothing changes the runtime outside the planned, recorded path.
-
Ownership-tracked cleanup
No broad garbage collection — 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.