Container Tool macOS 15 Limitations: Features Unavailable in Apple Container

The container tool on macOS 15 (Sequoia) restricts user-defined networks, container-to-container communication, and advanced vmnet features, requiring the use of a single default network with limited CIDR configuration.

The container tool from the apple/container repository provides Linux container support on macOS, but running on macOS 15 imposes significant constraints compared to macOS 26 and later. These limitations stem from the vmnet framework available in macOS 15, which lacks the APIs necessary for custom network bridges and isolated networking configurations.

Networking Restrictions on macOS 15

No User-Defined Container Networks

On macOS 15, the container network command family is unavailable. Attempting to create a custom network results in an error because the vmnet framework can only instantiate a single default network.

According to the technical documentation in docs/technical-overview.md, the vmnet implementation on macOS 15 does not expose the APIs required for custom network creation. When you attempt to use the --network flag with container run or container create, the CLI returns an error indicating that non-default network configuration requires macOS 26 or newer.

The source code in Sources/ContainerCommands/Network/NetworkCreate.swift explicitly guards network creation commands with #available(macOS 26, *) checks, preventing execution on macOS 15.

Isolated Container Communication

Container-to-container networking is impossible on macOS 15 because each container attaches to the default vmnet network in isolation. The vmnet implementation lacks the bridging functionality required to route traffic between containers, effectively isolating each runtime instance from the others.

As documented in Sources/Services/NetworkVmnet/Server/ReservedVmnetNetwork.swift, the @available(macOS 26, *) attribute governs the network bridging implementation, confirming that inter-container traffic requires the newer framework version.

Network Initialization Timing Issues

A critical timing limitation exists between the network XPC helper and vmnet initialization. On macOS 15, the network helper must start precisely when the first container launches; if it starts after vmnet initialization, subnet mismatches can leave containers without network access.

This occurs because vmnet’s initialization order on macOS 15 can cause the helper and vmnet to disagree on the CIDR address assignment. The platform defaults to 192.168.64.1/24 without the flexibility to reconfigure this subnet dynamically.

Fixed CIDR and Default Network Constraints

Advanced vmnet features—including custom CIDR blocks and isolated network segments—are unavailable. The system falls back to the hardcoded default configuration of 192.168.64.1/24 with no support for network segmentation or custom IP ranges.

CLI Commands and API Availability

Hidden Network Management Commands

Commands listed under the "Network Management (macOS 26+)" section in docs/command-reference.md are completely hidden from the macOS 15 CLI. These commands depend on private APIs introduced in macOS 26 that do not exist in the Sequoia release.

The command reference explicitly separates macOS 26+ functionality from the baseline macOS 15 interface, ensuring users cannot attempt operations that would fail at the framework level.

Availability Guards in Source Code

The codebase enforces macOS 15 limitations through Swift availability checks. In Sources/ContainerCommands/System/SystemStart.swift, the log root handling option is guarded by #available(macOS 26, *), meaning automatic log facility usage and certain system daemon behaviors require the newer operating system.

Similarly, in Sources/ContainerCommands/Machine/MachineCreate.swift at line 67, the --virtualization and --nested-virtualization flags include strict availability checks that limit functionality on macOS 15 hardware.

Virtualization and Security Limitations

Nested Virtualization Constraints

Nested virtualization via the --virtualization or --nested-virtualization flags requires Apple Silicon M3 or newer combined with macOS 15 or later. On macOS 15 systems lacking M3 silicon, or on older hardware configurations, these flags are ignored and raise an error.

The feature requires kernel support (CONFIG_KVM=y) that is not present on older platforms, and the implementation in MachineCreate.swift validates both hardware and OS version before attempting to initialize the virtual machine layer.

Packet-Filter and Security Restrictions

macOS 15 imposes stricter packet-filter constraints that limit certain security-related features. As documented in docs/how-to.md, packet-filter rule extensions and advanced network filtering capabilities have reduced functionality compared to macOS 26.

These limitations affect container network policies and egress filtering rules that rely on kernel-level packet inspection.

Working Within macOS 15 Constraints

When running on macOS 15, you must use the default vmnet network for all containers. The following examples demonstrate supported and unsupported operations:

# ❌ Fails on macOS 15 – network creation requires macOS 26

container network create mynet

# ❌ Fails on macOS 15 – custom network attachment unavailable

container run --network mynet -it alpine sh

# ✅ Works on macOS 15 – uses default vmnet network

container run -it ubuntu bash

# ✅ Works on macOS 15 – lists the single available default network

container network list

For production deployments on macOS 15, plan for isolated container instances without inter-service networking, and avoid configurations that depend on custom CIDR blocks or network segmentation.

Summary

• User-defined networks are unavailable on macOS 15; only the default vmnet network works.
• Container-to-container communication is impossible due to vmnet isolation limitations.
• Network initialization requires precise timing between the XPC helper and vmnet to avoid subnet mismatches.
• Advanced networking CLI commands are hidden behind macOS 26 availability guards in the source code.
• Nested virtualization requires M3 silicon and macOS 15+, but remains constrained by the older vmnet framework.
• Security features like packet-filter extensions face stricter limitations on macOS 15 than on macOS 26.

Frequently Asked Questions

Can I create custom container networks on macOS 15?

No. The container network create command and the --network flag require macOS 26 or newer. On macOS 15, the vmnet framework only supports a single default network with a fixed CIDR of 192.168.64.1/24.

Why can't containers communicate with each other on macOS 15?

macOS 15's vmnet implementation lacks the bridging APIs necessary to route traffic between containers. Each container attaches to an isolated default network, preventing inter-container traffic entirely. This functionality requires the updated vmnet framework available in macOS 26.

What happens if I try to use nested virtualization flags on older macOS 15 hardware?

The --virtualization and --nested-virtualization flags require both Apple Silicon M3 or newer and macOS 15 or later. On unsupported hardware, the command raises an error and ignores the flags, as the necessary kernel configuration (CONFIG_KVM=y) is unavailable.

Are there workarounds for the networking limitations on macOS 15?

No. The limitations are enforced at the framework level by the operating system's vmnet implementation. The apple/container source code explicitly checks for macOS 26 availability before exposing network management features, making these restrictions impossible to bypass on macOS 15.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}