Apple container
Apple's container is an open-source CLI for building, running, and managing OCI/Linux
containers on Apple-silicon Macs. Each container runs inside its own lightweight virtual
machine (backed by the Containerization framework and the Virtualization API), so there is no
shared daemon like Docker — services run per-user via launchd. Images are standard OCI
artifacts, so they interoperate with Docker registries and other OCI tooling. The CLI is
deliberately Docker-like (container run, container build, and image ops under
container image push/pull), but it is a distinct tool: do not assume Docker command paths,
flags, defaults, or daemon behavior carry over (e.g. there is no container images/push/pull
top-level command — image verbs live under container image).
Requirements
- Apple silicon only (M1 or later). Intel Macs are not supported.
- macOS 26 (Tahoe) is the officially supported target. The maintainers do not support
older macOS and typically will not fix issues that can't be reproduced on 26. The binary
still runs on macOS 15 (Sequoia) but with reduced networking: only the single default
subnet is available, and the
container network group and --network flag error out.
macOS-26-gated features are called out throughout the reference files.
- Version: this skill documents the 1.0.0 release (the fullest feature set). The
machine
group, container cp, container export, container prune, container image prune,
container registry list, and container system version were added in 1.0.0 (not in 0.7.1)
— features that postdate 0.7.1 are flagged (1.0.0+) in the reference files. Run container --version and
container <group> --help to see what your installed build supports.
- Install by downloading the signed
.pkg installer from the project's GitHub releases
(apple/container) and running it. See references/concepts.md for the full
requirements/compatibility matrix and how the VM-per-container model works.
Setup
Install the signed package, then start the background services once:
- Download the latest signed installer
.pkg from the
GitHub releases page.
- Double-click the downloaded package and follow the prompts, entering your admin
password so it can place files under
/usr/local. (There is no documented CLI installer
invocation — installation is via the GUI package.)
- Start the services and confirm they are healthy:
# Start the container services (container-apiserver + helpers via launchd). On first run it
# offers to install the default Linux kernel — accept it, or start non-interactively with
# `--disable-kernel-install` and add a kernel later via `container system kernel set`.
container system start
# Verify services are healthy
container system status
container system start must have run before any container/image/build command works — a
connection/XPC error almost always means the services are stopped, so run it again. Stop and
deregister the launchd services with container system stop (which takes only -p/--prefix).
The startup flags for container system start (-a/--app-root, --install-root, --log-root,
--enable-kernel-install/--disable-kernel-install, --timeout) are in
references/configuration.md.
Upgrade / downgrade / uninstall use helper scripts in /usr/local/bin (stop first with
container system stop): update-container.sh (add -v <version> to pin a version), and
uninstall-container.sh -d to remove user data or -k to keep it. Full recipes in
references/workflows.md.
Command groups at a glance
Invoke everything as container <group> <subcommand>. Container-lifecycle verbs (run,
create, start, stop, exec, logs, inspect, list/ls, delete/rm, kill,
stats) and build are top-level; image operations like push, pull, and tag live
under container image. Run container <group> --help for exact flags, or read
references/commands.md for the exhaustive matrix.
| Group |
What it does |
Example |
| container lifecycle |
Create, start, run, stop, exec, inspect, list, remove containers |
container run --rm -it docker.io/library/alpine sh |
| build |
Build an OCI image from a Dockerfile in the builder VM |
container build -t myapp:latest . |
| image |
List, tag, inspect, remove, load/save, prune local images; push/pull to registries |
container image ls |
| registry |
Authenticate (login/logout/list) to OCI registries |
container registry login ghcr.io |
| system |
Start/stop/status services, logs, disk usage (df), DNS, kernel, properties |
container system status |
| network |
Create/list/remove container networks (macOS 26 only) |
container network create mynet |
| volume |
Create/list/inspect/remove persistent volumes |
container volume create data |
| builder |
Manage the builder VM that runs container build (start/stop/status) |
container builder status |
| machine (1.0.0+) |
Persistent Linux "machine" environments (added in 1.0.0) |
container machine --help |
Exact subcommand names, aliases, arguments, and flags for each group live in
references/commands.md — consult it before running an unfamiliar command rather than
guessing Docker-equivalent syntax.
Navigating this skill
Read the reference file that matches the task; do not guess flags or behavior.
references/commands.md — exhaustive CLI reference: every command group, subcommand,
alias, argument, and flag. Read this to construct any concrete container ... invocation,
or to confirm a flag exists before using it.
references/concepts.md — architecture (VM-per-container, Containerization framework),
system requirements and macOS 15 vs 26 differences, networking model, per-container IPs,
security model, and a Docker-vs-container comparison. Read this to explain how or why
something works, or when a Docker mental model gives the wrong answer.
references/configuration.md — the system service, config.toml / property model,
default kernel, DNS domains, default registry, builder resources, and machine settings.
Read this to change defaults, tune CPU/memory, point at a private registry, or manage the
kernel.
references/workflows.md — copy-pasteable task recipes (run an image, build & push,
wire up local DNS, mount a volume, expose ports) and troubleshooting for common failures.
Read this first when the user wants to accomplish a concrete end-to-end task.
Key rules
- This is not Docker. The CLI resembles Docker, but flags, defaults, and daemon behavior
differ. Verify syntax in
references/commands.md instead of assuming Docker equivalence.
- Always ensure services are up first. Run
container system start (and confirm with
container system status) before any container/image/build command; connection errors
usually mean the services are stopped.
- Images are standard OCI artifacts and interoperate with Docker registries and other OCI
tools. Image references that omit a registry default to
docker.io (configurable via the
registry.domain property — see references/configuration.md).
- Each container gets its own IP address on its network (one lightweight VM per
container). There is no shared Docker bridge; reach a container directly by its IP, or set
up a local DNS domain (
container system dns create ..., admin required) for name-based
access.
container network requires macOS 26. On macOS 15 only the single default subnet is
available and the network command group is unavailable — see references/concepts.md.
- Use fully-qualified image references when precision matters (e.g.
docker.io/library/alpine rather than bare alpine) to avoid ambiguity about the source
registry.
1---
2name: apple-container
3description: |
4 Apple's open-source `container` CLI to build, run, and manage OCI/Linux containers as
5 lightweight per-container VMs on Apple-silicon macOS — no Docker daemon required. Use when
6 the user mentions the `container` CLI, "apple container", running or building containers on
7 macOS without Docker/Podman, `container run`, `container build`, `container images`,
8 `container system start`, pushing/pulling images to a registry, or container networking on
9 macOS. This is Apple's `container` tool specifically (repo `apple/container`), NOT Docker,
10 Podman, containerd, nerdctl, or Kubernetes — the CLI is Docker-like but is a different tool.
11license: Apache-2.0
12metadata:
13 source: https://skillmd.com/skills/gabrielmoreira/apple-container
14 author: sanjay3290
15 version: "1.0"
16---
17
18# Apple `container`
19
20Apple's `container` is an open-source CLI for building, running, and managing OCI/Linux
21containers on Apple-silicon Macs. Each container runs inside its own lightweight virtual
22machine (backed by the Containerization framework and the Virtualization API), so there is no
23shared daemon like Docker — services run per-user via `launchd`. Images are standard OCI
24artifacts, so they interoperate with Docker registries and other OCI tooling. The CLI is
25deliberately Docker-like (`container run`, `container build`, and image ops under
26`container image push`/`pull`), but it is a distinct tool: do not assume Docker command paths,
27flags, defaults, or daemon behavior carry over (e.g. there is no `container images`/`push`/`pull`
28top-level command — image verbs live under `container image`).
29
30## Requirements
31
32- **Apple silicon only** (M1 or later). Intel Macs are not supported.
33- **macOS 26 (Tahoe) is the officially supported target.** The maintainers do not support
34 older macOS and typically will not fix issues that can't be reproduced on 26. The binary
35 still runs on **macOS 15 (Sequoia)** but with reduced networking: only the single default
36 subnet is available, and the `container network` group and `--network` flag error out.
37 macOS-26-gated features are called out throughout the reference files.
38- **Version:** this skill documents the **1.0.0** release (the fullest feature set). The `machine`
39 group, `container cp`, `container export`, `container prune`, `container image prune`,
40 `container registry list`, and `container system version` were **added in 1.0.0** (not in 0.7.1)
41 — features that postdate 0.7.1 are flagged *(1.0.0+)* in the reference files. Run `container --version` and
42 `container <group> --help` to see what your installed build supports.
43- Install by downloading the signed `.pkg` installer from the project's GitHub releases
44 (`apple/container`) and running it. See `references/concepts.md` for the full
45 requirements/compatibility matrix and how the VM-per-container model works.
46
47## Setup
48
49Install the signed package, then start the background services once:
50
511. **Download** the latest signed installer `.pkg` from the
52 [GitHub releases page](https://github.com/apple/container/releases).
532. **Double-click** the downloaded package and follow the prompts, entering your admin
54 password so it can place files under `/usr/local`. (There is no documented CLI `installer`
55 invocation — installation is via the GUI package.)
563. **Start the services** and confirm they are healthy:
57
58```bash
59# Start the container services (container-apiserver + helpers via launchd). On first run it
60# offers to install the default Linux kernel — accept it, or start non-interactively with
61# `--disable-kernel-install` and add a kernel later via `container system kernel set`.
62container system start
63
64# Verify services are healthy
65container system status
66```
67
68`container system start` must have run before any container/image/build command works — a
69connection/XPC error almost always means the services are stopped, so run it again. Stop and
70deregister the `launchd` services with `container system stop` (which takes only `-p/--prefix`).
71The startup flags for `container system start` (`-a/--app-root`, `--install-root`, `--log-root`,
72`--enable-kernel-install`/`--disable-kernel-install`, `--timeout`) are in
73`references/configuration.md`.
74
75**Upgrade / downgrade / uninstall** use helper scripts in `/usr/local/bin` (stop first with
76`container system stop`): `update-container.sh` (add `-v <version>` to pin a version), and
77`uninstall-container.sh -d` to remove user data or `-k` to keep it. Full recipes in
78`references/workflows.md`.
79
80## Command groups at a glance
81
82Invoke everything as `container <group> <subcommand>`. Container-lifecycle verbs (`run`,
83`create`, `start`, `stop`, `exec`, `logs`, `inspect`, `list`/`ls`, `delete`/`rm`, `kill`,
84`stats`) and `build` are top-level; image operations like `push`, `pull`, and `tag` live
85under `container image`. Run `container <group> --help` for exact flags, or read
86`references/commands.md` for the exhaustive matrix.
87
88| Group | What it does | Example |
89|-------|--------------|---------|
90| container lifecycle | Create, start, run, stop, exec, inspect, list, remove containers | `container run --rm -it docker.io/library/alpine sh` |
91| build | Build an OCI image from a Dockerfile in the builder VM | `container build -t myapp:latest .` |
92| image | List, tag, inspect, remove, load/save, prune local images; push/pull to registries | `container image ls` |
93| registry | Authenticate (login/logout/list) to OCI registries | `container registry login ghcr.io` |
94| system | Start/stop/status services, logs, disk usage (`df`), DNS, kernel, properties | `container system status` |
95| network | Create/list/remove container networks (**macOS 26 only**) | `container network create mynet` |
96| volume | Create/list/inspect/remove persistent volumes | `container volume create data` |
97| builder | Manage the builder VM that runs `container build` (start/stop/status) | `container builder status` |
98| machine *(1.0.0+)* | Persistent Linux "machine" environments (added in 1.0.0) | `container machine --help` |
99
100Exact subcommand names, aliases, arguments, and flags for each group live in
101`references/commands.md` — consult it before running an unfamiliar command rather than
102guessing Docker-equivalent syntax.
103
104## Navigating this skill
105
106Read the reference file that matches the task; do not guess flags or behavior.
107
108- **`references/commands.md`** — exhaustive CLI reference: every command group, subcommand,
109 alias, argument, and flag. Read this to construct any concrete `container ...` invocation,
110 or to confirm a flag exists before using it.
111- **`references/concepts.md`** — architecture (VM-per-container, Containerization framework),
112 system requirements and macOS 15 vs 26 differences, networking model, per-container IPs,
113 security model, and a Docker-vs-`container` comparison. Read this to explain how or why
114 something works, or when a Docker mental model gives the wrong answer.
115- **`references/configuration.md`** — the system service, `config.toml` / property model,
116 default kernel, DNS domains, default registry, builder resources, and machine settings.
117 Read this to change defaults, tune CPU/memory, point at a private registry, or manage the
118 kernel.
119- **`references/workflows.md`** — copy-pasteable task recipes (run an image, build & push,
120 wire up local DNS, mount a volume, expose ports) and troubleshooting for common failures.
121 Read this first when the user wants to accomplish a concrete end-to-end task.
122
123## Key rules
124
125- **This is not Docker.** The CLI resembles Docker, but flags, defaults, and daemon behavior
126 differ. Verify syntax in `references/commands.md` instead of assuming Docker equivalence.
127- **Always ensure services are up first.** Run `container system start` (and confirm with
128 `container system status`) before any container/image/build command; connection errors
129 usually mean the services are stopped.
130- **Images are standard OCI artifacts** and interoperate with Docker registries and other OCI
131 tools. Image references that omit a registry default to `docker.io` (configurable via the
132 `registry.domain` property — see `references/configuration.md`).
133- **Each container gets its own IP address** on its network (one lightweight VM per
134 container). There is no shared Docker bridge; reach a container directly by its IP, or set
135 up a local DNS domain (`container system dns create ...`, admin required) for name-based
136 access.
137- **`container network` requires macOS 26.** On macOS 15 only the single default subnet is
138 available and the network command group is unavailable — see `references/concepts.md`.
139- **Use fully-qualified image references** when precision matters (e.g.
140 `docker.io/library/alpine` rather than bare `alpine`) to avoid ambiguity about the source
141 registry.