Chapter 2: Creating and Configuring Your Linux Container Machine

In the previous chapter, we prepared our macOS environment by installing essential developer tools. Now, it’s time to lay the foundation for our local container development: a lightweight Linux virtual machine (VM) running natively on your Apple Silicon Mac. This VM will serve as the host for all our containers, providing an ARM64 Linux environment that optimizes performance and ensures compatibility with modern container images.

This chapter focuses on creating and configuring this core container machine. By the end, you’ll have a fully functional Linux VM, managed by Colima, ready to receive and run OCI-compliant containers. This is a critical step, as it establishes the high-performance, native ARM64 execution environment that differentiates this approach from traditional x86-64 emulation or heavier Linux VMs.

Project Overview for This Chapter

This chapter is about establishing the core runtime environment for our containerized applications. We’re building a dedicated, optimized virtual machine on your Apple Silicon Mac that will host a container runtime. This VM is designed to be lean and efficient, leveraging Apple’s native hypervisor for near-native performance.

By the end of this chapter, you will have:

• Colima installed and configured on your macOS host.
• A dedicated ARM64 Linux virtual machine running via Apple’s Virtualization.framework.
• A containerd runtime active inside the VM, ready to manage OCI images.
• Your macOS docker CLI configured to seamlessly interact with this remote containerd instance.

This setup is the bedrock for building, running, and testing our containerized services in subsequent chapters.

Tech Stack: Leveraging Native Capabilities

To achieve our goal of a high-performance, native ARM64 container environment, we’ll use a specific set of tools:

• macOS (Apple Silicon): The host operating system, providing the Virtualization.framework. As of 2026-06-22, we recommend the latest stable macOS version (e.g., macOS 15.x Sequoia or later) for optimal performance and feature support from Virtualization.framework.
• Apple Virtualization.framework: The macOS-native hypervisor. This framework allows for highly efficient virtual machine execution directly on Apple Silicon, eliminating the overhead of full-blown hypervisors like VirtualBox or VMware Fusion for simple Linux guests. Its version is tied to your macOS version.
• Colima (Container Runtimes on Mac with Lima): A command-line tool that simplifies setting up container runtimes (like containerd or Docker) on macOS (and Linux) virtual machines. Colima abstracts away the complexities of Virtualization.framework (via Lima), making it easy to create and manage VMs that serve as container hosts. As of 2026-06-22, we’ll use the latest stable Colima release available via Homebrew.
• Lima (Linux on Mac): Colima uses Lima under the hood. Lima is a tool for running Linux virtual machines, primarily for container development, with support for various backends including Virtualization.framework and QEMU.
• containerd: An industry-standard core container runtime that manages the complete container lifecycle (image transfer, storage, execution, supervision, and networking). Colima can provision containerd inside the VM, offering a lightweight and robust runtime.
• Docker CLI: The familiar docker command-line interface. Colima configures this CLI on your macOS host to communicate with the containerd instance running inside the VM, providing a seamless user experience.

Milestones: Building Our Container Machine

This chapter is structured around these key milestones:

1. Install Colima: Get the orchestrator for our container machine onto your macOS host.
2. Start Colima Instance: Provision and launch a new ARM64 Linux VM with containerd using optimal settings for Apple Silicon.
3. Verify Setup: Confirm that the VM is running, accessible, and that your docker CLI can interact with its container runtime.

Each milestone builds upon the last, ensuring a solid foundation before moving to the next stage.

Architecture: How Colima Leverages Apple Virtualization

Apple’s Virtualization.framework provides the low-level APIs to run virtual machines on macOS, offering excellent performance by leveraging the native hypervisor. However, it’s a framework, not an end-user tool for managing Linux VMs or integrating with container runtimes like containerd or Docker. This is where Colima comes in.

Colima simplifies this by automatically handling:

• Downloading a minimal ARM64 Linux image (e.g., Alpine Linux or Ubuntu Cloud-init).
• Creating a VM definition using Virtualization.framework.
• Starting the VM with specified resources (CPU, memory, disk).
• Installing and configuring containerd (or Docker daemon) inside the VM.
• Setting up network access and exposing the container daemon socket to your macOS host.
• Configuring high-performance VirtioFS for file sharing between macOS and the Linux VM.

Decision Justification: We use Colima because it streamlines the setup process significantly. It provides a Docker CLI-compatible environment by exposing the daemon socket, and it leverages Virtualization.framework with VirtioFS by default on Apple Silicon, ensuring optimal performance and excellent file sharing capabilities.

Here’s a high-level overview of the components involved and their interaction:

Explanation of the Flow:

• Your macOS_Host is where you’ll run Colima commands and your docker CLI.
• The Colima_CLI acts as your interface to manage virtual machines.
• Colima then orchestrates Lima_Orchestrator to perform the actual VM creation and management.
• Lima leverages Apple’s Virtualization_Framework for native hypervisor performance, creating and running the Linux_VM.
• Inside the Linux_VM, the Containerd_Daemon runs, which is responsible for managing the lifecycle of your OCI_Containers.
• VirtioFS provides high-performance file sharing, allowing your macOS project directories to be seamlessly accessed within the Linux_VM.
• Crucially, Colima sets up the necessary networking and environment variables (DOCKER_HOST) so that your Docker CLI (or nerdctl) on the macOS_Host can directly communicate with the Containerd_Daemon inside the Linux_VM.

Step-by-Step Implementation: Setting Up Colima

We’ll now proceed with installing Colima and creating your first container machine.

Step 1: Install Colima

First, ensure Homebrew is installed, as Colima is distributed via Homebrew. If you haven’t installed it from Chapter 1, execute the following in your terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow any on-screen instructions to complete the Homebrew installation, including adding it to your PATH.

Once Homebrew is ready, install Colima. As of 2026-06-22, we recommend installing the latest stable Colima release to benefit from the most recent bug fixes and performance improvements.

brew install colima

What this command does: This command uses Homebrew to download and install the colima binary and its necessary dependencies, including Lima. You should see output indicating successful installation.

Step 2: Start Your First Colima Instance

Now, let’s start a Colima instance. We’ll configure it with reasonable defaults optimized for development on an Apple Silicon Mac.

colima start --cpu 4 --memory 8 --disk 100 --vm-type vz --arch arm64 --runtime containerd

Explanation of parameters and design choices:

• --cpu 4: Allocation Decision: This allocates 4 CPU cores to the virtual machine. This provides a good balance for typical development workloads, allowing multiple containerized services to run concurrently without excessively starving your macOS host. Tradeoff: You can adjust this based on your Mac’s total cores (e.g., an M1/M2/M3 Pro/Max/Ultra might handle more, a base M1 might prefer 2-3) and other concurrent tasks.
• --memory 8: Allocation Decision: This allocates 8 GB of RAM to the VM. This is often sufficient for running a few medium-sized services (e.g., a database, an API, and a cache). Tradeoff: While 4GB might be a minimum, 8GB offers more headroom and reduces the risk of out-of-memory errors for common development stacks. If your Mac has 16GB RAM, dedicating 8GB to Colima is a common and practical choice.
• --disk 100: Allocation Decision: This allocates a 100 GB virtual disk for the VM. This is where the Linux OS, container images, and any container volumes will reside. Tradeoff: 100GB is generous for most development needs, providing ample space for numerous images and project data without quickly filling up. You can start smaller (e.g., 50GB) if disk space is a concern, but remember that images can consume significant space over time.
• --vm-type vz: Crucial Performance Choice: This explicitly tells Colima to use Apple’s native Virtualization.framework (vz) for the VM. This is the default on Apple Silicon Macs but explicitly stating it ensures you’re leveraging the most performant virtualization backend. Benefit: This provides near-native performance for the Linux guest, significantly faster than QEMU-based emulation.
• --arch arm64: Native Execution: Specifies that the VM should be an ARM64 guest, matching your Apple Silicon host’s architecture. Benefit: This is essential for native performance, avoiding Rosetta 2 emulation overhead for the Linux kernel and userland, and ensuring your ARM64 container images run at full speed.
• --runtime containerd: Runtime Choice: Instructs Colima to set up containerd inside the VM. containerd is a robust, lightweight, and industry-standard container runtime. Colima will automatically configure the docker CLI on your host to communicate with this containerd instance via a Docker-compatible API, making it feel like you’re using Docker Desktop. Alternative: You could use --runtime docker if you prefer the classic dockerd daemon, but containerd is often preferred for its leaner footprint and direct integration into the OCI ecosystem.

When you run this command, Colima will perform several actions:

1. Image Download: It will check for a suitable ARM64 Linux image (e.g., Alpine or Ubuntu Cloud-init image). If not found locally, it will download one. This might take a few minutes depending on your internet connection.
2. VM Creation: It creates a Virtualization.framework VM with the specified CPU, memory, and disk resources.
3. OS Boot: The Linux VM is booted.
4. Runtime Setup: containerd (or dockerd if specified) is installed and configured within the VM.
5. Networking & Socket Exposure: Network access is set up, and the container runtime socket is exposed for communication with your macOS host.
6. File Sharing: VirtioFS is configured for efficient file sharing (this typically happens transparently).

You’ll see output similar to this during startup, indicating progress and successful setup:

INFO colima: starting colima on macOS (arch: arm64)
INFO colima: runtime "containerd"
INFO colima: vm-type "vz"
INFO colima: cpu: 4, memory: 8GiB, disk: 100GiB
INFO colima: starting ...
INFO [hostagent] starting
INFO [hostagent] waiting for ssh
INFO [hostagent] connected to the vm
INFO [hostagent] provisioning
INFO [hostagent] starting containerd
INFO [hostagent] starting userland docker
INFO [hostagent] mounting /Users/youruser:/Users/youruser
INFO [hostagent] done
INFO colima: "colima" is running

The line INFO [hostagent] mounting /Users/youruser:/Users/youruser is particularly important. It confirms that your macOS home directory is automatically mounted into the VM, which is very convenient for accessing project files from both the host and the container machine.

Step 3: Verify Your Colima Instance

After Colima reports that the instance is running, perform some checks to ensure everything is set up correctly.

Check Colima Status

Confirm your Colima instance is active and configured as expected.

colima status

Expected Output:

INFO colima: colima is running
ARCH: arm64
CPUS: 4
MEMORY: 8GiB
DISK: 100GiB
VM TYPE: vz
RUNTIME: containerd
...

This output should reflect the parameters you used to start Colima.

Access the Linux VM via SSH

You can SSH directly into your Colima VM to run Linux commands and inspect the guest environment.

colima ssh

Once inside the VM, you can verify the OS and architecture to confirm it’s an ARM64 Linux system:

uname -a

Expected Output (will vary slightly based on the specific Linux image downloaded, but should show aarch64):

Linux colima 6.x.x-alpine #1-Alpine SMP PREEMPT_DYNAMIC aarch64 Linux

You can also check the containerd service status within the VM:

sudo systemctl status containerd

Type exit to leave the VM and return to your macOS terminal.

Verify Docker CLI Integration

Colima automatically configures your DOCKER_HOST environment variable in your shell to point to its VM’s containerd (or docker) socket. This means your existing docker CLI (if installed, or nerdctl which Colima also often provides) should now work seamlessly.

Let’s test this by running a simple hello-world container. This will pull an ARM64 hello-world image and execute it within your Colima VM.

docker run --rm hello-world

Expected Output:

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
... (image download progress) ...
Hello from Docker!
This message shows that your Docker installation is working correctly.
...

This output confirms that your docker CLI on macOS is successfully communicating with the containerd runtime inside your Colima VM, and that the VM can pull and run ARM64 container images. This is the ultimate verification that your local container development environment is operational.

Testing & Verification

At this point, you should have successfully completed the following verifications:

1. Colima Status Check: Running colima status reports “colima is running” and displays the correct configuration parameters (CPU, memory, disk, vm-type vz, arch arm64, runtime containerd).
2. VM SSH Access: You can successfully connect to the Linux VM using colima ssh and verify its ARM64 architecture with uname -a.
3. Docker CLI Functionality: Your docker run --rm hello-world command executes successfully, pulling and running the container within the Colima VM, demonstrating full integration.

If all these checks pass, your native ARM64 container machine is fully set up and ready for use. If any step failed, consult the “Common Issues & Solutions” section below for troubleshooting.

Operations & Maintenance: Managing Your Local Environment

While Colima is for local development, understanding its operational aspects is crucial for maintaining a stable and performant workstation.

• Resource Allocation: The --cpu, --memory, and --disk parameters chosen during colima start are critical.
  • Over-allocation: Giving the VM too many resources can starve your macOS host, leading to a sluggish overall experience.
  • Under-allocation: Providing too few resources can cause your containers to crash, perform poorly, or fail to start.
  • Recommendation: Find a balance that suits your project’s needs and your Mac’s specifications. For most development setups, 4-8 CPU cores and 8-16GB RAM for the VM are good starting points on a 16GB+ Mac. You can always adjust these later by deleting and recreating the instance (colima delete then colima start with new parameters).
• VM Lifecycle Management:
  • colima stop: Gracefully shuts down the VM. This frees up CPU and memory resources when you’re not actively developing, saving battery and improving overall macOS performance.
  • colima start: Restarts your VM with its previous configuration. This is fast and brings your environment back online quickly.
  • colima delete: Permanently removes the VM and all its associated data (disk image, configuration). Use this when you’re done with a project, need to reset a corrupted instance, or want to reclaim disk space.
• Multiple Instances: For complex projects, specific testing scenarios, or to isolate dependencies, you can run multiple Colima instances by giving them unique names. This is a powerful feature for managing distinct development environments.

  colima start --name my-project-api-vm --cpu 2 --memory 4 --runtime containerd
  colima start --name my-project-db-vm --cpu 2 --memory 4 --runtime containerd

  You can then manage these instances by name (e.g., colima status my-project-api-vm, colima ssh my-project-db-vm, docker -c my-project-api-vm ps). This helps prevent conflicts between different project environments and allows for specialized configurations.

Common Issues & Solutions

• Error: vm-type "vz" is not available:
  • Cause: This usually means you are not on an Apple Silicon Mac, or your macOS version is too old to fully support Virtualization.framework for Linux guests. Virtualization.framework with vz is primarily supported on Apple Silicon (M1, M2, M3, etc.) and macOS 12 Monterey or later, with best performance on macOS 13 Ventura and newer.
  • Solution: Ensure you’re on an Apple Silicon Mac with the latest stable macOS version. If this is not possible, Colima will fall back to QEMU, which is still functional but might be slower.
• Error: failed to start vm: failed to start vm: exit status 1 or VM hangs on “starting…”:
  • Cause: Insufficient host resources (CPU or memory) or a corrupted VM image/configuration.
  • Solution:
    1. Try reducing the --cpu and --memory allocated to Colima in your colima start command.
    2. Check your macOS Activity Monitor for other resource-intensive applications.
    3. Delete and recreate the instance: colima delete then colima start ... with your desired parameters.
• docker run fails with Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?:
  • Cause: The Colima VM might not be running, or the DOCKER_HOST environment variable isn’t correctly set in your current shell session.
  • Solution:
    1. Run colima status to ensure the VM is running. If not, run colima start.
    2. Colima automatically sets DOCKER_HOST when it starts. If you opened a new terminal after starting Colima, you might need to source your shell’s configuration again (e.g., source ~/.zshrc or source ~/.bashrc), or simply restart Colima to ensure the environment variables are propagated.
    3. You can manually set it if needed (verify the path with colima status):

       export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"
       # Or if using containerd runtime directly with nerdctl:
       # export CONTAINERD_ADDRESS="unix://${HOME}/.colima/default/containerd.sock"

• Slow docker pull or apt update inside VM:
  • Cause: Network connectivity issues or slow DNS resolution within the VM.
  • Solution: Check your host’s internet connection. Colima uses NAT networking by default, which usually works well. If problems persist, you can SSH into the VM (colima ssh) and inspect DNS configuration (e.g., cat /etc/resolv.conf). Sometimes, restarting your host’s network interfaces or Colima itself can resolve transient issues.

Summary & Next Step

Congratulations! You’ve successfully established your core container development environment on your Apple Silicon Mac. You now have:

• Colima installed and managing your local container machines.
• A lightweight, ARM64 Linux VM running natively via Virtualization.framework.
• A functioning containerd runtime inside that VM.
• Your macOS docker CLI configured to interact seamlessly with this remote daemon.

This setup provides a highly performant and resource-efficient alternative to Docker Desktop for many workflows, leveraging the native capabilities of your Apple Silicon hardware. You’ve completed the crucial step of setting up the foundation.

In the next chapter, we’ll dive into one of the most critical aspects for developer productivity: efficiently mounting your macOS project directories into this Linux container machine. This will enable fast iteration and seamless file access between your host code editor and the containers running in your VM.

References

• Apple Developer Documentation: Virtualization.framework: https://developer.apple.com/documentation/virtualization
• Colima GitHub Repository (official documentation): https://github.com/abiosoft/colima
• Lima GitHub Repository (Colima’s underlying VM manager): https://github.com/lima-vm/lima
• Homebrew Documentation: https://docs.brew.sh
• containerd Project: https://containerd.io

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.