getting-started

Getting Started with Apple's Container Tool: Official Tutorial and Setup Guide

July 3, 2026 apple/container ↗

Yes, Apple provides a comprehensive "Start-Here" tutorial in the apple/container repository that teaches you how to build, run, and manage OCI-compatible containers on macOS 26 using the native container CLI.

Apple’s open-source container command-line utility brings native container support to macOS 26 and later, allowing developers to build, run, and publish OCI-compatible images without third-party tools. Written in Swift and hosted in the apple/container repository, this tool implements Docker-compatible sub-commands while leveraging macOS Virtualization frameworks for VM-grade isolation. The project includes official documentation in docs/tutorials/start-here.md that provides a complete getting started guide for new users.

Architecture Overview

The container tool uses a unique VM-per-container model that provides stronger isolation than traditional Linux containers while maintaining comparable startup performance.

When you invoke container system start, the tool launches a launch agent (container-apiserver) that spawns three helper processes: container-core-images for image management, container-network-vmnet for networking, and container-runtime-linux for the per-container runtime. According to the technical documentation in docs/technical-overview.md, each container runs inside its own minimal Linux VM using Apple's Containerization Swift package alongside the macOS Virtualization, vmnet, XPC, launchd, and Keychain frameworks.

This architecture automatically installs a default Linux kernel on first use and includes macOS-specific conveniences like an embedded DNS service for local container resolution.

Prerequisites

Before following the tutorial, ensure your environment meets these requirements:

  • macOS 26 or later running on Apple silicon (ARM64)
  • Administrative privileges for initial service setup and DNS configuration
  • Internet connection for downloading the Linux kernel on first run

Step-by-Step Tutorial: Building Your First Container

The official tutorial in docs/tutorials/start-here.md demonstrates a complete workflow using a Python web server example. Follow these commands in your terminal to get started:

1. Initialize the Container Service

Start the background service, which installs the default Linux kernel automatically on first run:

container system start

2. Verify Service Status

Confirm the daemon is running and view existing containers:

container list --all

3. Create a Project Directory and Dockerfile

Create a test project with a minimal Python web server:

mkdir web-test && cd web-test
cat > Dockerfile <<'EOF'
FROM docker.io/python:alpine
WORKDIR /content
RUN apk add curl
RUN echo '<!DOCTYPE html><html><head><title>Hello</title></head><body><h1>Hello, world!</h1></body></html>' > index.html
CMD ["python3", "-m", "http.server", "80", "--bind", "0.0.0.0"]
EOF

4. Build the Container Image

Tag the image as "web-test" using the build command that mirrors Docker syntax:

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

5. Run the Container

Start the container in detached mode with auto-removal on exit:

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

6. Access the Running Service

View the container's IP address and open it in your browser:

container ls
open http://192.168.64.3

7. Configure Local DNS (Optional)

Create a local DNS domain "test" for cleaner URLs:

sudo container system dns create test
open http://my-web-server.test

8. Monitor Runtime Statistics

Inspect resource usage without streaming updates:

container stats --no-stream my-web-server

9. Execute Commands Inside the Container

Run interactive commands within the running VM:

container exec my-web-server ls /content

10. Cleanup and Shutdown

Stop the container and terminate the background service:

container stop my-web-server
container system stop

Core Workflow Concepts

The tutorial demonstrates four essential phases of the Apple container lifecycle:

  1. Service Management – Use container system start to initialize the VM infrastructure and container system stop to release resources
  2. Image Building – The container build command supports standard Dockerfiles and OCI registries, caching layers in container-core-images
  3. Container Execution – Each container run invocation creates an isolated Linux VM via container-runtime-linux with unique IP allocation from container-network-vmnet
  4. Inspection and Debugging – The CLI provides container ls, container stats, and container exec for operational visibility

Essential Documentation Resources

The apple/container repository provides a complete learning path through these specific files:

  • docs/tutorials/start-here.md – The step-by-step getting started guide covering the Python web server example
  • docs/technical-overview.md – Deep dive into the VM-per-container architecture, helper processes, and macOS framework integration
  • docs/command-reference.md – Comprehensive listing of all CLI sub-commands and options
  • docs/how-to.md – Advanced usage patterns including registry authentication, networking configuration, and DNS setup
  • README.md – Project overview, installation instructions, and system requirements

Summary

  • Apple maintains an official "Start-Here" tutorial at docs/tutorials/start-here.md that teaches container basics through a practical Python web server project
  • The container CLI requires macOS 26 and Apple silicon, using a VM-per-container model for isolation via the container-runtime-linux process
  • Commands mirror Docker syntax (build, run, exec, stats) but add macOS-specific features like the container system dns command for local domain resolution
  • The architecture relies on Swift-based helper processes (container-apiserver, container-core-images, container-network-vmnet) and macOS Virtualization frameworks
  • Complete documentation covers tutorials, technical architecture, command reference, and how-to guides in the repository's docs/ directory

Frequently Asked Questions

What macOS version do I need to run Apple's container tool?

You need macOS 26 or later running on Apple silicon (ARM64) architectures. The tool leverages macOS Virtualization frameworks that are only available in these versions, and it automatically installs a Linux kernel on first use when you run container system start.

How does Apple's container tool differ from Docker Desktop?

While the container CLI implements familiar Docker-compatible commands like build, run, and image, it uses a VM-per-container architecture rather than sharing a single Linux VM. As implemented in apple/container, each container runs in its own minimal Linux VM via the container-runtime-linux process, providing VM-grade isolation while maintaining startup performance comparable to traditional containers.

Where can I find the complete command reference for the container CLI?

The complete command reference is documented in docs/command-reference.md in the repository. This file lists all available sub-commands, flags, and options for the container binary, including macOS-specific extensions like container system dns for managing local DNS services.

Does the tutorial require existing Docker knowledge?

No, the "Start-Here" tutorial in docs/tutorials/start-here.md assumes no prior container experience. It walks through creating a Dockerfile, building an image, and running containers using only the container CLI. However, if you know Docker, the sub-command syntax will feel immediately familiar, as the tool mirrors standard Docker workflows for building and running OCI-compatible images.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →