Understanding the Differences Between Container Machines and Regular Containers

Container machines provide a full Linux environment with init system support and persistent storage, while regular containers isolate single applications with ephemeral filesystems.

In the Apple Container repository, container machines represent a specialized abstraction that extends standard container capabilities. Unlike typical containers designed for single-process isolation, container machines model entire Linux hosts with proper init systems and user context. This article examines the architectural distinctions between these two approaches based on the implementation in docs/container-machine.md and related source files.

What Are Container Machines?

Container machines are a specialized type of container implemented in the Apple Container project that provide a complete Linux environment rather than the typical single-process focus of ordinary containers. According to the documentation in docs/container-machine.md, these machines run a full init system as PID 1, enabling system-level operations that standard containers cannot support. They are designed to function as persistent, user-aware development environments that bridge the gap between virtual machines and lightweight containers.

Key Differences Between Container Machines and Regular Containers

Purpose and Architecture

Standard containers optimize for running one application or service in isolation, making them ideal for microservices and stateless workloads. Container machines model an entire Linux host, including the init system, allowing many long-running services to coexist within the same environment. As documented in docs/container-machine.md, this architectural difference enables container machines to host complex applications requiring multiple background services, such as databases or development toolchains.

Init System and Service Management

Standard containers typically run the application process as PID 1, lacking a proper init system. Container machines explicitly start /sbin/init as the first process, enabling tools like systemctl to function correctly. This distinction, detailed in docs/container-machine.md lines 7-9, means you can install and manage system services using native Linux package managers and service managers inside a container machine.

Persistence and Storage

Standard containers maintain ephemeral filesystems where data disappears when the container stops unless explicitly mounted volumes are used. Container machines provide built-in persistent storage where the machine's root filesystem survives stop and start cycles. This persistence model, described in the technical documentation, allows you to install packages and modify system configurations that remain available across sessions.

User Integration and Home Mapping

While standard containers require manual user configuration and volume mounts, container machines automatically map the host macOS username and home directory into the Linux environment. As specified in docs/container-machine.md lines 8-10, the path /home/<you> mirrors $HOME from the host, ensuring seamless file access without copy operations. This automatic mapping eliminates the friction typically encountered when sharing files between macOS and Linux containers.

Host Integration

Regular containers impose limited host-to-container interaction, requiring manual file mounting and network configuration. Container machines enable seamless macOS-native tooling where editors, profilers, and browsers see the same files the container sees, as noted in docs/container-machine.md lines 10-12. This integration allows you to edit files in macOS-native applications while building and testing them in the Linux environment without synchronization steps.

Nested Virtualization Support

Standard containers do not support nested virtualization. Container machines can expose /dev/kvm when the host hardware and kernel permit, enabling nested virtualization for development scenarios requiring hardware acceleration. According to docs/container-machine.md lines 75-80, this feature requires Apple Silicon M3 or later and macOS 15 or newer, allowing developers to run additional virtualization layers inside their container machines.

Practical Usage Examples

Create a container machine from an OCI image to establish a persistent Linux environment:

# Create a container machine from an OCI image

container machine create alpine:latest --name dev

Run commands as your macOS user inside the machine, with automatic home directory mapping:

# Run a command as your macOS user inside the machine

container machine run -n dev whoami               # prints your host username

container machine run -n dev pwd                  # shows /home/<you>

Open an interactive shell after setting a default machine:

# Open an interactive shell (default machine if set)

container machine set-default dev
container machine run

Adjust computational resources, which take effect after restart:

# Resize resources – changes take effect after a restart

container machine set -n dev cpus=4 memory=8G
container machine stop dev
container machine run -n dev -- nproc

Enable nested virtualization for hardware-accelerated development:

# Enable nested virtualization (requires Apple Silicon M3+ + macOS 15+)

container machine create \
    --virtualization \
    --kernel /path/to/vmlinux-kvm \
    --name kvm-dev alpine:latest
container machine run -n kvm-dev -- ls -l /dev/kvm

Build a custom image with systemd support for full system management:

# Build and use a custom image that includes systemd

# Dockerfile excerpt (see docs for full file)

FROM ubuntu:24.04
ENV container container
RUN apt-get update && apt-get install -y dbus systemd ...

# Build the image and create a machine from it

container build -t local/ubuntu-machine:latest .
container machine create local/ubuntu-machine:latest --name ubuntu

When to Use Container Machines vs Regular Containers

Choose container machines when you need:

• A full Linux development environment with persistent state
• Systemd or other init system functionality
• Automatic home directory synchronization with macOS
• Multiple long-running services in a single environment
• Nested virtualization capabilities

Choose regular containers when you need:

• Ephemeral, stateless application isolation
• Minimal resource overhead for single-process workloads
• CI/CD pipeline execution without system service requirements
• Distribution-specific testing without full system initialization

Summary

• Container machines run a full Linux init system (/sbin/init) while regular containers run a single process as PID 1.
• Container machines provide persistent root filesystems that survive restarts, unlike the ephemeral storage of standard containers.
• Automatic mapping of macOS user identities and home directories (/home/<you>) occurs in container machines but requires manual configuration in regular containers.
• Nested virtualization via /dev/kvm is available only in container machines and requires Apple Silicon M3+ with macOS 15+.
• The implementation details are documented in docs/container-machine.md, docs/technical-overview.md, and demonstrated in examples/container-machine-vscode/README.md.

Frequently Asked Questions

Can container machines run systemd services?

Yes. Container machines explicitly start /sbin/init as PID 1, enabling systemd and other init systems to function. This allows you to install packages with apt-get, yum, or apk and manage services using systemctl commands. According to docs/container-machine.md lines 7-9, this is a primary architectural distinction from standard containers.

How does home directory mapping work in container machines?

Container machines automatically map the host macOS username and home directory into the Linux environment. Your host $HOME directory appears at /home/<you> inside the machine, enabling seamless file editing between macOS applications and Linux tools. This integration is documented in docs/container-machine.md lines 8-10 and eliminates the need for manual volume mounts.

Are container machines slower than regular containers?

Container machines consume more resources than standard containers because they run a full init system and provide persistent storage. However, they offer significantly lower overhead than traditional virtual machines while providing similar functionality. The performance characteristics depend on the allocated CPU and memory, which you can adjust using container machine set as shown in docs/command-reference.md.

Can I run Docker inside a container machine?

Yes, through nested virtualization support. Container machines can expose /dev/kvm when running on Apple Silicon M3 or later with macOS 15 or newer, as documented in docs/container-machine.md lines 75-80. This allows you to run hardware-accelerated virtualization workloads, including nested container runtimes, inside your container machine environment.

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