Apple Container

The Apple Container backend uses Apple's container CLI to run Linux containers as lightweight VMs on Mac. OCI-compatible images (e.g. Ubuntu 24.04) run in a Linux guest. It supports shell, Python, and Node.js (all inside the Linux guest). macOS 26 is recommended for full support.

Requirements

  • macOS with Apple silicon
  • container CLI installed and on PATH (typically /usr/local/bin/container after install)

Installation

  1. Install the container CLI

    Download the signed installer from Apple's container releases, or build from source.

  2. Start the system service

    container system start

  3. Verify

    Ensure container is on your PATH. To list running containers use container list or container list --all (not container ls).

  4. Build and sign heyvm (macOS)

    For the Apple Container backend to work, the heyvm binary must be signed with the hypervisor entitlement. From the mvm-ctrl directory:

    make

    Or build and sign manually; see the mvm-ctrl README for entitlements.xml and signing steps.

After this, heyvm can use the apple_container backend. Default image is Ubuntu 24.04 LTS (ubuntu:24.04). For more detail, see the mvm-ctrl README.

Note: There is also an apple_virt backend that uses the native Virtualization.framework directly (no container CLI required). It boots Alpine Linux VMs via EFI/GRUB, supports shell sandboxes, and is the default for heyvm wt on macOS.