Early design and implementation

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.

Read the docs View on GitHub ↗

See the change before it happens.

Every run computes a reviewable plan from your manifest. Today plan is non-mutating — it shows the diff and applies nothing. Mutation, when it lands, must cross the same recorded path.

hostwright plan non-mutating 
$ hostwright plan∙ reading hostwright.yaml∙ validating manifest … ok∙ computing plan (non-mutating)   project: api-local   + create   service/api      ghcr.io/example/api:latest  + create   service/redis    redis:7  ~ map      ports            8080→8080, 6379→6379   plan: 2 to create, 1 to configure, 0 to destroy ✓ no changes applied — review, then apply

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 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.

A small, honest CLI

hostwright — core in design 
hostwright init
hostwright validate
hostwright plan
hostwright status
hostwright doctor
hostwright — later Planned 
hostwright apply
hostwright down --dry-run

The command surface is still in design. These are the intended shapes, not a shipped tool — commands marked Planned are not implemented yet.

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.

Layered architecture: the hostwright CLI and planned daemon sit above the RuntimeAdapter boundary, which drives Apple's container runtime and Linux VMs.
Apple container is the execution substrate. Hostwright currently owns manifest validation and non-mutating planning; runtime reconciliation, health, drift, and cleanup are planned behind the RuntimeAdapter boundary.

Declare a stack in one file

hostwright.yaml 
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"
A stack is declared in a single readable file. Each field shown here is documented in the manifest reference.

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.

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.

Legend Planned In progress Implemented Blocked

What it deliberately does not do yet

Stated openly. A narrow, defensible first release matters more than a broad one.

Architectural — not changing

  • 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.

Under research — not committed

  • Tunnel and DNS integration

    Cloudflare, Tailscale, or WireGuard integration. Research-only — no commitment yet.

  • GPU-aware scheduling

    Apple GPU/ANE scheduling, plus Metal, Core ML, or MLX container support. Research-only.

Separately: this is an early infrastructure project under active design — nothing here is production-ready yet. That one changes as the project matures, not by design decision.

Follow along