TestcontainerEx.Connection.Strategies.AppleContainer (testcontainer_ex v0.7.1)

Copy Markdown View Source

Resolves the container engine host for Apple Container (https://github.com/apple/container).

Apple Container is a macOS-native container runtime for Apple silicon Macs. It runs a lightweight VM per container using the open source Containerization package, providing VM-level isolation with container-like performance.

Unlike Docker/Podman, Apple Container does not expose a Docker-compatible HTTP API. Instead, it uses XPC for interprocess communication between the container CLI and the container-apiserver launch agent. The apiserver manages container and network resources via XPC helpers:

  • container-core-images — image management and local content store
  • container-network-vmnet — virtual network management
  • container-runtime-linux — per-container runtime management

This strategy activates when:

  • The container binary is available on PATH (or via CONTAINER_BIN env var)
  • The host is running macOS 26+ (Apple Container requires macOS 26 or later)
  • The container-apiserver launch agent is registered with launchd
  • The Apple Container system service reports "running" status
  • The API server socket exists at /var/run/com.apple.container.apiserver

The strategy returns a special URL scheme apple-container:// that downstream code uses to route operations through the container CLI.

System requirements

Configuration

No special configuration is required beyond having container installed and running on an Apple silicon Mac.

Environment variables

  • CONTAINER_BIN — override the path to the container binary (default: searches PATH for container)
  • CONTAINER_ENGINE=apple_container — explicitly select Apple Container

Apple Container architecture

Apple Container uses a fundamentally different architecture than Docker:

  • Each container runs in its own lightweight VM (not a shared VM)
  • The container-apiserver is a launch agent (not a daemon)
  • Communication is via XPC, not HTTP REST API
  • Images are standard OCI images (interoperable with Docker)
  • Networking uses vmnet framework with per-container isolation

See https://github.com/apple/container/blob/main/docs/technical-overview.md for the full technical overview.