How Container Machines Differ from Standard Containers in Apple Container

Container machines provide a full Linux environment with an init system, persistent storage, and seamless macOS integration, whereas standard containers isolate single processes with ephemeral storage.

The apple/container repository introduces a container machine feature that bridges the gap between lightweight containerization and full virtual machines. Unlike standard containers designed to run a single application in isolation, container machines model an entire Linux host complete with service management and persistent state. This distinction fundamentally changes how developers interact with containerized environments on macOS.

Core Architectural Differences

Init System and Service Management

Standard containers typically run a single process as PID 1, meaning they lack an init system and cannot manage background services like databases or system daemons. In contrast, container machines start /sbin/init as the first process, enabling standard Linux tools such as systemctl according to docs/container-machine.md. This allows multiple long-running services to coexist within the same environment.

Storage Persistence and Filesystem Lifecycles

Standard containers treat storage as ephemeral—data disappears when the container stops unless explicitly mounted to external volumes. Container machines, however, maintain persistent storage by default; the machine's root filesystem survives stop and start cycles, providing a stateful development environment similar to a traditional Linux workstation.

Automatic User and Home Directory Mapping

While standard containers require manual configuration to map host users, container machines automatically integrate with the host macOS system. The current macOS username and home directory are mapped directly into the Linux environment at /home/<username>, mirroring the host's $HOME directory as documented in docs/container-machine.md. This eliminates the need for manual volume mounts when accessing personal files.

macOS Integration and Development Workflow

Seamless Host-Container File Access

Standard containers require explicit volume mounts to share files between host and container, creating friction when using external editors or profilers. Container machines provide seamless macOS-native tooling integration—editors, profilers, and browsers running on the host see the same files the container sees without copy steps or manual synchronization, as noted in docs/container-machine.md.

Multi-Distribution Flexibility

You can create multiple container machines based on different Linux distributions—such as Alpine, Ubuntu, or Debian—while sharing the same home directory across all instances. This flexibility allows developers to test against various distro configurations without sacrificing their personal environment settings, according to the feature documentation in docs/container-machine.md.

Advanced Capabilities and Nested Virtualization

Container machines support capabilities unavailable in standard containers, including nested virtualization. When running on Apple Silicon M3+ with macOS 15+, container machines can expose /dev/kvm to the guest environment, enabling kernel-based virtual machine workloads within the container. Standard containers cannot provide this functionality, as they lack the infrastructure to pass through virtualization extensions.

Working with Container Machines: Practical Examples

Creating a container machine from an OCI image initializes a persistent Linux environment:

# Create a container machine from an OCI image

container machine create alpine:latest --name dev

The machine automatically maps your macOS identity, allowing you to run commands as your host user:

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

Set a default machine to simplify interactive access:

# Open an interactive shell (default machine if set)

container machine set-default dev
container machine run

Resource allocation can be adjusted dynamically, though changes require a 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            # verifies new CPU count

For development requiring virtualization, enable nested KVM support:

# 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

To run system services like databases, build a custom image including systemd:

# 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

Summary

• Container machines provide a full Linux environment with /sbin/init, enabling service management tools like systemctl, while standard containers run a single process as PID 1.
• Persistence is built into container machines—the root filesystem survives restarts—whereas standard containers are ephemeral unless configured with external volumes.
• User integration happens automatically in container machines, mapping the host macOS username and home directory to /home/<you>, eliminating manual volume configuration.
• macOS tooling works seamlessly with container machines, allowing host editors and profilers to access the same files as the container without copy steps.
• Nested virtualization is available only in container machines, exposing /dev/kvm when hardware and kernel support permit.

Frequently Asked Questions

Can I run system services like PostgreSQL or Nginx inside a container machine?

Yes. Container machines start /sbin/init as the first process, allowing you to use systemctl and other standard Linux service management tools. This enables running multiple long-running background services simultaneously, which is not possible in standard containers that typically run only a single foreground process.

How does file persistence work compared to Docker volumes?

Unlike standard containers, which lose their filesystem state when stopped unless using external volumes, container machines maintain persistent storage by default. The root filesystem survives stop and start cycles, providing a stateful environment similar to a traditional Linux workstation without requiring explicit volume mounts.

Can I use my existing macOS development tools with a container machine?

Yes. Container machines automatically map your macOS home directory into the Linux environment at /home/<username>. This seamless integration means editors, profilers, and browsers running on macOS can access the same files the container sees, eliminating the need for manual file copying or synchronization steps.

What are the requirements for nested virtualization support?

Nested virtualization requires Apple Silicon M3 or later running macOS 15 or newer. When these conditions are met, you can create a container machine with the --virtualization flag and a compatible KVM kernel to expose /dev/kvm inside the container, enabling workloads that require hardware-assisted virtualization.

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