Apple Container Agent Skill

Apple container

When to Use

• Use when building, running, or managing OCI/Linux containers on Apple-silicon macOS with Apple's open-source container CLI
• Use when you want lightweight per-container VMs instead of a Docker daemon
• Use when translating Docker-style workflows (build, run, exec, logs, networking) to Apple's container tooling

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).

Safety Gate

Container installation, service startup, image pulls, builds, runs, registry login, pushes,

and resource cleanup change local or remote state. Explain the exact command, image registry,

mounts, ports, privileges, and data-persistence impact, then obtain explicit user approval

before executing it. Do not provide registry credentials, mount sensitive paths, or expose

ports without the user's explicit instruction.

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.

Limitations

• Apple Container requires Apple silicon and has materially different support and networking

behavior across macOS releases; verify the installed CLI version before relying on a flag.

• OCI images and registry content are third-party inputs. Inspect and trust the image source

before pulling or running it.

• This skill does not make container workloads safe by default: mounts, published ports,

privileged settings, registry credentials, and cleanup can expose or destroy data.

• Stop before uninstalling, pruning, deleting containers, volumes, or images, and require

explicit approval for each destructive action.