Build and run OCI containers on Apple silicon with container CLI

Guides building, running, and managing OCI/Linux containers on Apple-silicon macOS using Apple's open-source container CLI. 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 and interoperate with Docker registries and other OCI tooling. The CLI is deliberately Docker-like (container run, container build, image operations under container image push/pull) but is a distinct tool: Docker command paths, flags, defaults, and daemon behavior do not carry over - there is no top-level container images/push/pull, since image verbs live under container image.

Container installation, service startup, image pulls, builds, runs, registry logins, pushes, and cleanup all change local or remote state, so the skill explains the exact command, image registry, mounts, ports, privileges, and data-persistence impact and obtains explicit user approval before executing, never supplying registry credentials, mounting sensitive paths, or exposing ports without explicit instruction.

Setup requires downloading the signed .pkg installer from the apple/container GitHub releases page, running it via the GUI installer (there is no documented CLI install path), then starting background services with container system start (which offers to install the default Linux kernel on first run, or can run non-interactively with --disable-kernel-install) and confirming health with container system status - a connection or XPC error almost always means the services are stopped. Services stop and deregister with container system stop. Upgrade, downgrade, and uninstall use helper scripts in /usr/local/bin: update-container.sh (with -v <version> to pin a version) and uninstall-container.sh (-d to remove user data, -k to keep it).

Command groups, invoked as container <group> <subcommand>: container lifecycle verbs (run, create, start, stop, exec, logs, inspect, list/ls, delete/rm, kill, stats) and build sit at the top level; image handles list/tag/inspect/remove/load/save/prune and registry push/pull; registry handles login/logout/list against OCI registries; system covers service start/stop/status, logs, disk usage, DNS, and kernel management; network creates/lists/removes container networks (macOS 26 only); volume manages persistent volumes; builder manages the VM that runs container build; and machine (added in version 1.0.0) provides persistent Linux "machine" environments.

Use it when building, running, or managing OCI/Linux containers on Apple-silicon macOS, when lightweight per-container VMs are wanted instead of a Docker daemon, or when translating Docker-style workflows to Apple's tooling.

Do NOT assume Docker command paths, flags, defaults, or daemon behavior carry over - verify syntax in the bundled command reference instead of guessing Docker equivalence. Do NOT run it on Intel Macs - Apple silicon (M1 or later) is required. Do NOT expect the full command set on macOS 15 (Sequoia): only the single default subnet is available and the container network group and --network flag are unavailable there; macOS 26 (Tahoe) is the officially supported target and the maintainers typically will not fix issues that can't be reproduced on it.

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 and postdate 0.7.1. Running container --version and container <group> --help shows what the installed build supports. Four bundled reference files cover the exhaustive CLI (every command, subcommand, alias, argument, flag), architecture and concepts (VM-per-container model, macOS 15 vs 26 differences, networking, security model, Docker comparison), configuration (service config, config.toml, default kernel, DNS domains, default registry, builder resources), and copy-pasteable workflow recipes (run an image, build and push, wire up local DNS, mount a volume, expose ports, troubleshoot common failures).

Images interoperate with Docker registries and other OCI tooling; references that omit a registry default to docker.io (configurable via the registry.domain property). Each container gets its own IP address on its network rather than sharing a Docker bridge - reach a container directly by IP or set up a local DNS domain (container system dns create, admin required) for name-based access. Fully-qualified image references (docker.io/library/alpine rather than bare alpine) are recommended to avoid registry-source ambiguity.

Developers on Apple-silicon Macs who want Docker-style container workflows without a shared daemon, running each container in its own lightweight VM via Apple's native container tooling.