How to Use Apple Container, the Open-Source Docker Alternative in Swift

Containers have become an indispensable tool. They offer portability, consistency, and efficiency, allowing developers to build and deploy applications reliably across different environments. For years, Docker has been the de-facto standard on macOS, but a new challenger, born right out of Apple, is poised to offer a more native, integrated, and streamlined experience for developers on Apple Silicon: container.

container is a new open-source tool from Apple that lets you create and run standard, OCI-compliant Linux containers on your Mac. Written entirely in Swift and optimized for Apple Silicon, it's designed to be a lightweight, high-performance alternative to other container runtimes. It leverages macOS's own virtualization technologies to run containers as minimal, isolated virtual machines, promising better security and a smaller footprint.

This article provides a deep dive into Apple's container project. We'll explore its architecture, its key benefits, and then walk through a comprehensive tutorial on how to build, run, and share your first containerized application. Whether you're a seasoned backend developer or a curious Mac user, you'll find everything you need to get started with this exciting new tool.

Why a New Container Tool? The Vision Behind container

In a landscape dominated by established players, why did Apple decide to build its own container tool? The answer lies in a vision for a deeply integrated, performant, and developer-friendly experience on its own hardware and software. container isn't just another Docker clone; it's a re-imagining of what containerization can be on a Mac.

Native Performance on Apple Silicon

Unlike other solutions that may rely on heavier Linux virtual machines or cross-platform compatibility layers, container is built from the ground up for Apple Silicon. It's a Swift application that talks directly to Apple's native Virtualization.framework. This results in a significant performance advantage. There's no emulation layer like Rosetta 2 involved for the runtime itself, and each container runs in its own lightweight VM, booting in a fraction of the time it takes to launch a full-fledged virtual machine.

A Uniquely Secure Architecture

Security is a cornerstone of the container design. The technical overview reveals a key architectural decision: instead of running all containers within a single, shared Linux VM, container launches a dedicated, minimal micro-VM for each container.

This "one VM per container" model provides robust hardware-level isolation. A process escaping its container would find itself inside a heavily restricted, single-purpose VM, not in a shared environment with access to other containers. This significantly reduces the potential attack surface and enhances the overall security posture of your development environment.

OCI Compliance: Playing Well with Others

Despite its unique architecture, container fully embraces open standards. It consumes and produces Open Container Initiative (OCI) compliant images. This is a critical feature, as it means you aren't locked into a proprietary ecosystem. You can pull a standard image from Docker Hub, run it with container, build a new image, and push it back to any OCI-compliant registry like GitHub Container Registry (ghcr.io). Your container-built images will work seamlessly in other tools and in production CI/CD pipelines.

Deep macOS Integration

container is a good citizen on macOS. It integrates with core system technologies to provide a smooth user experience:

• Virtualization & Networking: Uses Virtualization.framework and vmnet for efficient VM and network management.
• Service Management: The container-apiserver daemon is managed by launchd, the standard way to manage services on macOS.
• Security: Leverages Keychain services for securely storing registry credentials.
• Logging: Integrates with the macOS unified logging system, so all its diagnostic output is in a familiar place.

Under the Hood: A Quick Technical Deep Dive

The container command-line tool (container) is a client that communicates with a background server process, container-apiserver. This server, which you start with container system start, manages everything.

When you issue a command like container run, the API server launches a dedicated runtime helper (container-runtime-linux) for that specific container. This helper, in turn, uses the Virtualization.framework to spin up a new, minimal Linux VM that hosts your container's processes. This architecture is elegant, robust, and designed for security and performance.

It's important to note that, as a new project, container has some limitations. It requires a modern version of macOS (macOS 15, with best performance on the latest macOS 26 Beta 1). Networking between containers and the host has some specific workarounds, and advanced features like memory ballooning are still under development. However, the foundation is strong and the project is evolving rapidly.

How to Use container: A Step-by-Step Tutorial

Let's get our hands dirty. This tutorial will guide you through the entire lifecycle of a container: building an image for a simple web server, running it, interacting with it, and publishing it.

Step 1: Installation and Setup

First, ensure you meet the requirements: an Apple Silicon Mac running a recent version of macOS.

Install container: Download the latest signed installer package from the project's GitHub release page. Double-click the .pkg file and follow the installation prompts.

Start the Service: Open your terminal and start the container system services.

container system start

The first time you run this, it will likely prompt you to download and install a default Linux kernel. Type y and press Enter to proceed.

Verify the Installation: Check that the service is running by listing all available containers (which should be none at this point).

container ls -a
# You should see empty headers:
# ID  IMAGE  OS  ARCH  STATE  ADDR

Step 2: Building Your First Image

Now, let's create a container image for a simple Python web server.

Create a Project Directory:

mkdir web-test
cd web-test

Create a Dockerfile: Inside the web-test directory, create a file named Dockerfile (or Containerfile) with the following content. This file defines the "recipe" for our image.

# Start from a lightweight Python base image
FROM docker.io/python:alpine

# Set the working directory inside the container
WORKDIR /content

# Add the 'curl' utility for testing
RUN apk add curl

# Create a simple HTML file
RUN echo '<!DOCTYPE html><html><head><title>Hello from Container</title></head><body><h1>Hello, Apple Container!</h1></body></html>' > index.html

# The command to run when the container starts
CMD ["python3", "-m", "http.server", "80", "--bind", "0.0.0.0"]

Build the Image: Now, tell container to build an image from your Dockerfile. We'll tag it with the name web-test.

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

The . at the end tells the builder to use the current directory as its context.

List Your Images: After the build completes, you can see your new image in the local image store.

container images list
# You should see your `web-test` image and the `python:alpine` base image.
# NAME      TAG     DIGEST
# python    alpine  b4d299311845...
# web-test  latest  25b99501f174...

Step 3: Running Your Container

With our image built, let's run it.

Run the Web Server: Use the container run command to start a container from your web-test image.

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

Let's break down those flags:

• -name my-web-server: Gives our container a memorable name.
• -detach (or d): Runs the container in the background.
• -rm: Automatically removes the container's record when it stops, keeping things tidy.

Check the Running Container: List the active containers.

container ls

You'll see your my-web-server container in the running state, along with its assigned IP address in the ADDR column (e.g., 192.168.64.3).

Access Your Web Server: Open a web browser and navigate to the IP address shown in the previous step. You should see your "Hello, Apple Container!" message.

# Replace the IP with the one from `container ls`
open <http://192.168.64.3>

Step 4: Interacting with the Container

container provides powerful tools to interact with your running containers.

Execute a Command: You can run commands directly inside the container using container exec. Let's list the files in our web server's content directory.

container exec my-web-server ls /content
# Output: index.html

Open an Interactive Shell: For more complex debugging, you can get an interactive shell inside the container.

container exec -it my-web-server sh

The -it flags (--interactive and --tty) are crucial for connecting your terminal to the shell inside the container. You'll be dropped into a shell prompt inside your container's WORKDIR. You can look around, check processes, and then type exit to return to your Mac's terminal.

Step 5: Publishing Your Image

Sharing your work is easy. Let's push our image to a container registry. This example uses Docker Hub, but any OCI registry will work. (This assumes you have a Docker Hub account with username fido).

Log In to the Registry:

# This will prompt for your username and password/token
container registry login docker.io

Tag the Image for Publishing: Registries require images to be named in a registry/username/image:tag format. Let's create a new tag for our image.

container images tag web-test docker.io/fido/web-test:latest

Push the Image:

container images push docker.io/fido/web-test:latest

Your image is now available for others to pull and run, on any OCI-compliant platform!

Step 6: Cleaning Up

Once you're done, you can stop the container and shut down the service.

# Stop the container
container stop my-web-server

# Stop all container services
container system stop

Beyond the Basics

The tutorial covers the core workflow, but container can do more. Here are a few features from the how-to.md documentation:

Resource Management: You can control the resources allocated to your containers. For memory-intensive builds, you can give the builder more RAM and CPUs:

container builder start --cpus 8 --memory 16g

File Sharing: You can mount a directory from your Mac into the container using the -volume flag, which is essential for development workflows where you want to edit code on the host and see the changes live in the container.

container run --volume ${HOME}/my-project:/app my-image

Multi-Platform Builds: You can build images that run on both Apple Silicon (arm64) and Intel (amd64) architectures in a single command, perfect for deploying to diverse server environments.

container build --arch arm64 --arch amd64 --tag my-multi-arch-image .

Advanced Inspection: The container inspect command provides detailed JSON information about containers and images, which is useful for scripting and automation.

Conclusion

Apple's container is more than just a new tool; it's a statement. It signals a commitment to providing first-class, integrated developer tools for the modern era of cloud-native development. By building a lightweight, secure, and performant container runtime directly into the OS, Apple is lowering the barrier to entry for containerization on the Mac and offering a compelling alternative to incumbent solutions.

While the project is still young, its foundation is solid, its architecture is sound, and its adherence to open standards ensures it will be a valuable player in the wider container ecosystem. If you're a developer on an Apple Silicon Mac, container is a project you should be watching—and trying—today.