# How to Run Linux Containers as Lightweight VMs Using Apple's Container Runtime

> Learn how to run Linux containers as lightweight VMs using Apple's container runtime. Achieve VM-level isolation with container startup speeds on macOS.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-07-01

---

**Yes, Apple's `container` runtime runs each Linux container inside its own lightweight virtual machine using the macOS Virtualization and vmnet frameworks, delivering VM-level isolation with container startup speeds.**

Apple's open-source `container` repository introduces a unique approach to containerization on macOS by running Linux containers as lightweight VMs. This architecture leverages the **Containerization** Swift package alongside native macOS frameworks to provide hardware-isolated containers without the overhead of traditional virtualization. If you are looking to run Linux containers as lightweight VMs using Apple's container runtime, this guide explains the technical implementation and practical usage based on the actual source code.

## Architecture: Per-Container Lightweight VMs

### VM-Level Isolation for Every Container

Unlike traditional container runtimes that share a single Linux kernel among all containers, Apple's implementation creates a dedicated lightweight VM for each container. According to [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md), the `container-runtime-linux` helper spins up a minimal VM specifically for the container being started. This design provides the same isolation guarantees as full virtual machines while consuming significantly less memory than standard VM instances.

### macOS Framework Integration

The runtime integrates deeply with macOS-specific technologies to manage the lightweight VM lifecycle:

- **Virtualization framework**: Handles VM creation and management
- **vmnet**: Provides networking capabilities for the isolated environments
- **XPC**: Enables inter-process communication between `container-apiserver` and helpers
- **Launchd**: Manages the `container-apiserver` as a launch agent
- **Keychain**: Securely stores registry credentials

## Runtime Flow and Implementation

When you execute `container system start`, the runtime initializes a chain of services defined in [`src/container-apiserver/main.swift`](https://github.com/apple/container/blob/main/src/container-apiserver/main.swift). This launches the `container-apiserver`, which coordinates with XPC helpers including `container-core-images` and `container-network-vmnet`.

For each container creation, the system invokes the `container-runtime-linux` helper implemented in [`src/container-runtime-linux/main.swift`](https://github.com/apple/container/blob/main/src/container-runtime-linux/main.swift). This helper is responsible for instantiating the lightweight VM that will host the specific Linux container. The flow follows this sequence: `container system start` → `container-apiserver` → XPC helpers → `container-runtime-linux` → lightweight VM for the container.

## Running Linux Containers as Lightweight VMs

To run Linux containers as lightweight VMs using Apple's container runtime, use the following CLI commands.

Start the container service to launch the apiserver and VM infrastructure:

```bash
container system start

```

Build an OCI-compatible image:

```bash
container build --tag web-test --file Dockerfile .

```

Run a container, which creates a fresh lightweight VM:

```bash
container run --name my-web-server --detach --rm web-test

```

Verify the VM-backed container is running and view its assigned IP address:

```bash
container ls

```

Example output showing the VM network assignment:

```

ID             IMAGE      OS      ARCH   STATE    IP
my-web-server  web-test   linux   arm64  running  192.168.64.3

```

Execute commands inside the container's VM:

```bash
container exec my-web-server uname -a

```

The output confirms the Linux kernel running inside the lightweight VM:

```

Linux my-web-server 6.12.28 #1 SMP Tue May 20 15:19:05 UTC 2025 aarch64 Linux

```

Inspect the runtime helper and VM configuration:

```bash
container inspect my-web-server

```

Stop and remove the container, which automatically terminates its associated VM:

```bash
container stop my-web-server

```

## Key Source Files

The implementation relies on these critical components from the `apple/container` repository:

- **[`src/container-apiserver/main.swift`](https://github.com/apple/container/blob/main/src/container-apiserver/main.swift)**: Launches the apiserver and manages XPC helpers that coordinate VM creation
- **[`src/container-runtime-linux/main.swift`](https://github.com/apple/container/blob/main/src/container-runtime-linux/main.swift)**: The runtime helper that instantiates the lightweight VM for each container
- **[`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md)**: Detailed architectural documentation describing the per-container VM model
- **[`README.md`](https://github.com/apple/container/blob/main/README.md)**: Project overview and getting started guide

## Summary

- Apple's `container` runtime runs each Linux container in its own lightweight VM using the macOS Virtualization framework
- The architecture provides VM-level isolation while maintaining full OCI image compatibility with Docker and Podman
- Key components include `container-apiserver` and `container-runtime-linux` helpers that manage the VM lifecycle through XPC
- The system uses native macOS technologies including vmnet for networking and Launchd for service management
- Containers boot as fast as traditional containers but with the security boundaries of full virtual machines

## Frequently Asked Questions

### Does each container really get its own VM?

Yes. Unlike Docker Desktop or other solutions that run containers inside a shared Linux VM, Apple's `container` runtime creates a dedicated lightweight virtual machine for every container. This implementation in [`src/container-runtime-linux/main.swift`](https://github.com/apple/container/blob/main/src/container-runtime-linux/main.swift) ensures complete kernel-level isolation between containers while the VM optimized core utilities keep resource usage minimal.

### How does this compare to Docker Desktop for Mac?

Docker Desktop uses a single Linux VM to host all containers, sharing the same kernel across the namespace boundary. Apple's `container` runtime creates individual lightweight VMs per container using the macOS Virtualization framework. This provides stronger isolation guarantees at the cost of slightly different resource characteristics, though each VM is optimized to boot quickly and consume far less memory than a full-size virtual machine.

### What Linux kernel version runs inside the lightweight VMs?

The example output from `uname -a` shows Linux kernel 6.12.28 running inside the VM, though specific versions may vary by release. The kernel runs inside the lightweight VM created by the `container-runtime-linux` helper, providing full Linux compatibility for OCI images built with other container tools.

### Can I run existing Docker images with Apple's container runtime?

Yes. The `container` tool consumes and produces OCI-compatible images, meaning images built with Docker, Podman, or other OCI-compliant tools run unchanged inside these lightweight VMs. You can build images using `container build` and run them without modification to the image format, as the runtime handles the VM abstraction transparently.