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

> Understand the functional differences between container-runtime-linux for per-container sandboxes and container-network-vmnet for host-wide virtual networking in Apple Container.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: deep-dive
- Published: 2026-06-17

---

**`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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift) | Declares the network helper binary and version information |
| [`Sources/Plugins/NetworkVmnet/config.toml`](https://github.com/apple/container/blob/main/Sources/Plugins/NetworkVmnet/config.toml) | Default configuration for vmnet networking parameters |
| [`Sources/ContainerResource/Container/ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/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:

```bash

# 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`](https://github.com/apple/container/blob/main/ContainerConfiguration.swift) (lines 48-50) bakes in these defaults. To inspect the network allocation provided by `container-network-vmnet`:

```bash

# 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:

```bash
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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.