# Getting Started with Apple's Container Tool: Official Tutorial and Setup Guide
> Learn to build, run, and manage OCI containers on macOS with Apple's official container tool. Follow our tutorial for easy setup and get started today.
- Repository: [Apple/container](https://github.com/apple/container)
- Tags: getting-started
- Published: 2026-07-03
---
**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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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:
```bash
container system start
```
### 2. Verify Service Status
Confirm the daemon is running and view existing containers:
```bash
container list --all
```
### 3. Create a Project Directory and Dockerfile
Create a test project with a minimal Python web server:
```bash
mkdir web-test && cd web-test
cat > Dockerfile <<'EOF'
FROM docker.io/python:alpine
WORKDIR /content
RUN apk add curl
RUN echo 'HelloHello, world!
' > 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:
```bash
container build --tag web-test --file Dockerfile .
```
### 5. Run the Container
Start the container in detached mode with auto-removal on exit:
```bash
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:
```bash
container ls
open http://192.168.64.3
```
### 7. Configure Local DNS (Optional)
Create a local DNS domain "test" for cleaner URLs:
```bash
sudo container system dns create test
open http://my-web-server.test
```
### 8. Monitor Runtime Statistics
Inspect resource usage without streaming updates:
```bash
container stats --no-stream my-web-server
```
### 9. Execute Commands Inside the Container
Run interactive commands within the running VM:
```bash
container exec my-web-server ls /content
```
### 10. Cleanup and Shutdown
Stop the container and terminate the background service:
```bash
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`](https://github.com/apple/container/blob/main/docs/tutorials/start-here.md)** – The step-by-step getting started guide covering the Python web server example
- **[`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md)** – Deep dive into the VM-per-container architecture, helper processes, and macOS framework integration
- **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md)** – Comprehensive listing of all CLI sub-commands and options
- **[`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md)** – Advanced usage patterns including registry authentication, networking configuration, and DNS setup
- **[`README.md`](https://github.com/apple/container/blob/main/README.md)** – Project overview, installation instructions, and system requirements
## Summary
- Apple maintains an official **"Start-Here" tutorial** at [`docs/tutorials/start-here.md`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.