Functional Differences Between container-runtime-linux and container-network-vmnet in Apple Container

container-runtime-linux manages per-container Linux sandboxes and exposes the full container runtime API, while container-network-vmnet operates as a host-wide XPC service that provides virtual network interfaces via the macOS vmnet framework.

The Apple Container project uses a modular helper architecture where specialized binaries handle distinct aspects of container lifecycle management. Understanding the functional differences between the runtime and network helpers is essential for debugging container networking issues and optimizing sandbox configurations.

Core Architectural Roles

The two helpers operate at different scopes within the container stack. One manages individual container instances, while the other manages shared host resources.

container-runtime-linux: Per-Container Sandbox Manager

The container-runtime-linux helper functions as an XPC service dedicated to managing a Linux sandbox for a single container instance. According to the source code in Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift (lines 23-25), this binary defines the command name and serves as the primary interface between the container APIs and the underlying Linux runtime.

Its core responsibilities include:

• Starting and configuring the container's sandbox with root privileges and resource limits
• Exposing the complete container-runtime API including bootstrap, create process, state, stop, kill, resize, wait, start, dial, shutdown, statistics, and copy in/out operations
• Loading network plugins (specifically container-network-vmnet by default) to establish connectivity
• Running per-container—the container-apiserver launches a new instance of this helper for every container it creates

The implementation details in Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper+Start.swift (lines 28-84) reveal how the start sub-command wires the XPC server, event-loop, and networking strategies together during initialization.

container-network-vmnet: Host-Wide Virtual Network Provider

In contrast, container-network-vmnet provides virtual network infrastructure through the macOS vmnet framework. Defined in Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift (lines 23-25), this helper runs once per host to service all containers requesting vmnet-based networking.

Its primary functions include:

• Allocating virtual network interfaces for individual containers
• Assigning IP addresses and configuring routing tables
• Setting up the vmnet "bridge" to connect containers to the host network
• Supplying the networking backend that container-runtime-linux references by plugin name

Configuration defaults for this plugin reside in Sources/Plugins/NetworkVmnet/config.toml.

How the Helpers Interact Over XPC

The architectural separation requires precise coordination between the per-container runtime and the shared network service.

Runtime Initialization of Network Strategies

When container-runtime-linux starts, it builds an interfaceStrategies dictionary that references the network plugin by its identifier. In RuntimeLinuxHelper.Start.run() (lines 68-72), the runtime specifically requests container-network-vmnet to allocate network resources. This setup configures two modes:

• allocationOnly for isolated interfaces
• reserved for non-isolated interfaces (available on macOS 26+)

XPC Route Communication

The network helper implements XPC routes such as allocateAttachment and releaseAttachment (exposed through its XPC interface). When the runtime creates a container endpoint, it calls these routes to request virtual NIC allocation. This allows the container's Linux processes to communicate through a fully functional network interface supplied by the vmnet framework.

The container-apiserver orchestrates this relationship by launching the network helper once for the host, then launching individual runtime helpers for each container as documented in the technical overview (lines 47-48).

Source Code Locations and Implementation Details

Key files that define the functional boundary between these helpers include:

File	Purpose
Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift	Declares the runtime helper binary and command structure
Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper+Start.swift	Implements XPC server setup and network plugin loading
Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift	Declares the network helper binary and version information
Sources/Plugins/NetworkVmnet/config.toml	Default configuration for vmnet networking parameters
Sources/ContainerResource/Container/ContainerConfiguration.swift	Lines 48-50 define the default --runtime and --plugin values

Practical Usage Examples

While these helpers run automatically under normal operation, you can explicitly specify them when creating containers:

# Create a container using the specific helpers

container create \
    --runtime container-runtime-linux \
    --plugin container-network-vmnet \
    --image my-app:latest \
    my-container

The --runtime and --plugin flags are optional because ContainerConfiguration.swift (lines 48-50) bakes in these defaults. To inspect the network allocation provided by container-network-vmnet:

# View the vmnet-provided IP and gateway

container network inspect my-container

# Output shows assigned IP (e.g., 192.168.64.2/24) and routing details

When executing commands inside the container, the runtime helper handles the sandbox operations behind the scenes:

container exec my-container /bin/bash

Summary

• container-runtime-linux operates as a per-container XPC service managing Linux sandbox lifecycle and runtime APIs, defined in Sources/Plugins/RuntimeLinux/
• container-network-vmnet runs once per host to provide vmnet-based virtual networking to all containers, defined in Sources/Plugins/NetworkVmnet/
• The runtime helper loads the network plugin by reference, calling XPC routes like allocateAttachment to establish container connectivity
• Both helpers are configured as defaults in ContainerConfiguration.swift (lines 48-50), making explicit flags optional
• The architecture separates concerns: sandbox management scales per-container while network interface allocation scales per-host

Frequently Asked Questions

How do I know which helper is running for my container?

Each container-runtime-linux process runs in direct association with a specific container instance and terminates when that container stops. You can identify active runtime helpers using process inspection tools—the binary name appears as container-runtime-linux in the process list. The container-network-vmnet helper runs continuously as a single instance per host, serving all containers simultaneously.

Can I use container-runtime-linux without container-network-vmnet?

While technically possible by specifying a different --plugin, the default configuration in ContainerConfiguration.swift (lines 48-50) pairs container-runtime-linux with container-network-vmnet. The runtime expects a network plugin to satisfy its interfaceStrategies requirements during initialization in RuntimeLinuxHelper+Start.swift. Removing the network plugin would require providing an alternative networking implementation that exposes compatible XPC routes.

What macOS version is required for vmnet networking?

The container-network-vmnet helper utilizes the macOS vmnet framework available on modern macOS versions. The source code specifically references non-isolated interface support (reserved) for macOS 26+, while isolated interfaces (allocationOnly) work on earlier versions. Check Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift for version-specific feature availability.

Where are the default helper paths configured?

Default helper binaries are hardcoded in Sources/ContainerResource/Container/ContainerConfiguration.swift at lines 48-50. The system defaults to container-runtime-linux for the runtime and container-network-vmnet for networking unless explicitly overridden via CLI flags or configuration files.

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