How to Manage Container Networking with vmnet Using the container CLI

The container CLI uses Apple's vmnet framework through the container-network-vmnet XPC service to provide virtual Ethernet networking for Linux containers, automatically allocating IP addresses when you start the system service and run containers.

The container open-source project from Apple leverages the native vmnet kernel extension to bridge Linux containers with macOS networking. To manage container networking with vmnet using the container CLI, you interact with a thin command-line interface that delegates network creation, IP reservation, and interface configuration to a dedicated XPC helper service.

How vmnet Integration Works in container

The architecture isolates network responsibilities within a dedicated XPC service called container-network-vmnet. This service implements the vmnet API to create virtual networks, handle serialization, and supply IP configurations to running containers.

Core Components and Source Files

Several key source files define this integration:

• Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift – Registers the XPC helper with the container daemon and declares the container-network-vmnet plugin metadata.
• Sources/Services/NetworkVmnet/Server/ReservedVmnetNetwork.swift – Contains the core vmnet creation logic, including IPv4/IPv6 configuration, network reservation, and serialization handling.
• Sources/ContainerResource/Network/NetworkConfiguration.swift – Stores the default plugin name (container-network-vmnet), which the CLI uses when you omit the --plugin flag.
• Sources/Services/RuntimeLinux/Server/NonisolatedInterfaceStrategy.swift – Works alongside IsolatedInterfaceStrategy to determine whether a container receives a full network interface or just an address allocation.

macOS Version Requirements and Limitations

vmnet support varies significantly by macOS version, affecting which CLI features are available.

macOS 15 only provides isolated host-only networks. Container-to-container traffic is explicitly not supported, which disables the container network subcommands and causes the --network flag on container run or container create to error.

macOS 26 restores full vmnet functionality. You can create custom networks with specific CIDR blocks (defaulting to 192.168.64.0/24), and containers communicate freely across the virtual network.

Managing vmnet Networks via CLI

The workflow for managing container networking with vmnet follows three main phases: system initialization, optional custom network creation, and container attachment.

Starting the System Service

Initialize the default vmnet network by starting the system service:

container system start

This command creates the default vmnet network and registers it with the vmnet kernel extension. The container-network-vmnet helper begins listening for allocation requests via XPC.

Creating Custom Networks (macOS 26+)

On macOS 26, create isolated network segments with custom subnets:

container network create mynet --subnet 10.10.0.0/24

The CLI forwards this request to the vmnet helper, which constructs a new vmnet network with your specified CIDR range.

Attaching Containers to Networks

Run containers attached to specific networks using the --network flag:

container run -it --network mynet alpine sh

If you omit the --network flag, the container automatically attaches to the default network.

Inspecting Network Allocations

The container-network-vmnet service logs all IP allocations to the system log. A typical entry appears as:

container-network-vmnet: allocated attachment [hostname=my-web-server.test.] [address=192.168.64.2/24] [gateway=192.168.64.1] [id=default]

You can monitor these allocations through the macOS Console app or by querying the system logs directly to verify which addresses the vmnet helper has assigned to specific containers.

Summary

• The container CLI delegates all vmnet operations to the container-network-vmnet XPC service, keeping the interface thin while leveraging native macOS networking.
• NetworkVmnetHelper.swift registers the plugin, while ReservedVmnetNetwork.swift handles the actual vmnet API calls for network creation and IP management.
• Start the system service with container system start to initialize the default 192.168.64.0/24 network.
• macOS 15 restricts networking to isolated mode only, while macOS 26 supports custom CIDRs and container-to-container communication.
• Use container network create on macOS 26+ to define custom subnets, and attach containers with the --network flag.

Frequently Asked Questions

What is the default network plugin for container?

The default plugin is container-network-vmnet, as defined in Sources/ContainerResource/Network/NetworkConfiguration.swift. You can override this with the --plugin flag according to the command reference, but the vmnet helper remains the standard for macOS deployments.

Why are network commands disabled on macOS 15?

macOS 15's vmnet implementation only supports isolated host-only networks without container-to-container communication. Because this limitation prevents meaningful multi-container networking, Apple disables the container network subcommands and rejects the --network flag on macOS 15 to prevent configuration errors.

How do containers receive IP addresses from vmnet?

When a container starts, the runtime invokes the strategy defined in NonisolatedInterfaceStrategy.swift (or IsolatedInterfaceStrategy.swift), which communicates with the container-network-vmnet XPC service. The service queries the vmnet kernel extension and returns an IP address from the available pool, typically from the 192.168.64.0/24 range for the default network.

Can I use a custom CIDR for vmnet networks?

Yes, but only on macOS 26 and later. When running container network create, specify your desired subnet with the --subnet flag. The vmnet helper validates this CIDR and configures the virtual network accordingly, allowing you to segment containers into specific IP ranges.

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