Apple container boundary

Hostwright does not run containers. Apple container runs containers; Hostwright validates what should run, observes what is running, and mutates only through narrow confirmed gates. Every one of those interactions crosses the RuntimeAdapter. Understanding where that line sits is essential to understanding the project.

What Apple container provides

Apple container is a Mac-native runtime built for Apple silicon. The properties that matter for Hostwright:

• A VM-per-container model: each container runs in its own lightweight Linux VM.
• An OCI image flow, so standard container images work.
• A command surface and helper services managed under macOS, with vmnet-based networking.

The VM-per-container model is a defining constraint: replicas and large stacks carry real per-VM memory overhead, which shapes Hostwright’s conservative resource posture. See Limitations.

The path of a runtime operation

hostwright CLI / hostwrightd
  → RuntimeAdapter
    → Apple container CLI, or the Containerization framework via
      hostwright-containerization-helper
      → Apple container services
        → lightweight Linux VM
          → your container process

Everything above the adapter is Hostwright. Everything below it is Apple’s.

What Hostwright owns

• Manifest parsing, validation, and deterministic planning.
• Drift detection, health probes, restart policy, and the event ledger.
• The ownership ledger and conservative, token-confirmed cleanup.
• Confirmed lifecycle mutation (create, start, stop, restart, remove, update), image management, and interactive access, each behind its own plan hash or confirmation gate. See Lifecycle commands.

What Apple container owns

• The container and VM lifecycle internals.
• The image store and registry interactions.
• The networking stack and system helpers.

Verified shapes only

Hostwright adapts documented, locally verified Apple container CLI behavior only. The current command shapes are based on verified Apple container 1.0.0 output; they are not a broad Apple CLI compatibility claim. If local output does not match a reviewed parser shape, Hostwright fails closed with a parse error rather than guessing.

No reaching past the seam

Hostwright does not reimplement, patch, or assume the internals of Apple container, and it must not depend on private helper internals or undocumented behavior. When the runtime cannot do something, Hostwright reports it as a limitation rather than hiding it behind a vague error.

Open questions at the boundary

exec, attach, copy, export, inspect, stats, and logs --follow are implemented; see Interactive and streaming commands. What remains open depends on Apple container behavior:

• Port-forwarding semantics beyond published loopback ports.
• Log retention and rotation for long-lived containers.
• Localhost HTTP reachability evidence: on some proof hosts, the Apple container listener accepts then resets while macOS Local Network access for container-runtime-linux is disabled.