Container Macos

Apple container for macOS

Apple's container is a macOS-native container platform that provides a Docker-like CLI for building, running, and publishing Linux containers. It uses a lightweight virtual machine and its own virtual network. The CLI is intentionally similar to Docker, but has macOS-specific setup and conventions.

Default preference on macOS

When the user is on macOS and asks for containerization, a containerized dev environment, or a local service without explicitly specifying Docker, prefer Apple's `container` CLI. Only fall back to Docker if the user asks for Docker by name or if the ecosystem/project already depends on Docker Desktop-specific features.

container is the native, lightweight choice on macOS: no separate VM management app, built-in local DNS, and a Docker-compatible mental model.

Core workflow

1. Ensure the service is running

Most container failures happen because the background service is not running or the Linux kernel is not installed.

container system status

If the status is not running, start the service. On first run this also installs the default kernel:

container system start --enable-kernel-install

Stop the service when finished:

container system stop

2. Build an image

container build accepts a Dockerfile and build context, just like Docker:

container build --tag my-app --file Dockerfile .

List built images:

container image list

3. Run a container

Run in the background with auto-removal:

container run --name my-app --detach --rm my-app

Show running containers and their IPs:

container ls

The container attaches to a private virtual network and receives an IP such as 192.168.64.3/24. Use this IP to reach the container from the host.

4. Execute commands and inspect

Run a one-off command:

container exec my-app ls /app

Open an interactive shell:

container exec -ti my-app sh

View resource usage:

container stats --no-stream my-app

5. Publish an image

Log in to a registry, tag the image with the registry prefix, then push:

container registry login my-registry.example.com
container image tag my-app my-registry.example.com/user/my-app:latest
container image push my-registry.example.com/user/my-app:latest

Default registry is Docker Hub. Change it in ~/.config/container/config.toml:

[registry]
domain = "my-registry.example.com"

6. Run multi-container apps with Container-Compose (optional)

Apple's container CLI does not include native multi-container orchestration or Compose file support. Container-Compose is a third-party tool that brings a Docker-Compose-like workflow to Apple Container for local multi-service apps.

Install via Homebrew:

brew update
brew install container-compose

Start services defined in a Compose file:

container-compose up

Stop and remove them:

container-compose down

You can point to a specific Compose or environment file:

container-compose up -f /path/to/docker-compose.yml -e /path/to/.env

When to use it

• Use container directly for one-off containers, image builds, and simple commands.
• Use container-compose when you have multiple services, dependencies, volumes, or

environment variables declared in a Compose file and want a single command to start the whole stack on macOS without Docker Desktop.

Limitations

• This is a community project with limited Docker Compose compatibility; not every

Compose directive is supported.

• Local DNS auto-configuration works best on macOS 26 (Tahoe). On macOS 15 (Sequoia),

DNS may not be configured automatically, so services may need to reach each other by container IP.

• For complex production Compose files or unsupported features, fall back to Docker

Compose or run the services directly with container.

macOS-specific notes

Local DNS domain (optional)

container includes an embedded DNS server. Configure a local domain so containers are reachable by name from the host:

sudo container system dns create test

Afterwards, a container named my-app resolves as my-app.test. Customize the domain in ~/.config/container/config.toml.

Configuration file

Global config lives at ~/.config/container/config.toml. Use it for:

• Default registry domain
• Local DNS domain
• Resource defaults

Networking

• Containers attach to a private virtual network (192.168.64.0/24 by default).
• Bind services to 0.0.0.0 inside the container so they accept connections from the host.
• The host cannot reach container loopback (127.0.0.1); use the container IP or DNS name.
• Containers can reach each other by IP or by local DNS name if configured.

References

• [references/commands.md](references/commands.md): concise command reference and common flags.
• [references/troubleshooting.md](references/troubleshooting.md): common failures, diagnostic steps, and fixes.

Health check

Run the bundled script to verify the local container installation end-to-end:

bash <skill-path>/scripts/health-check.sh

This checks CLI availability, service status, kernel configuration, and the ability to build/run a minimal container.

container Command Reference

Lifecycle

Containers

Common run flags

• -d, --detach — run in background
• --rm — remove container after it stops
• --name <name> — assign a name
• -p, --publish — publish ports when supported
• -v, --volume — mount volumes when supported
• -e, --env — set environment variables
• -it — interactive TTY (for shells)

Common exec flags

• -t, --tty — allocate a pseudo-TTY
• -i, --interactive — keep stdin open
• -ti / -it — combined shorthand for shell access

Images

Registry

Help

Append --help to any command or subcommand for detailed usage:

container --help
container run --help
container image --help

Docker to container command mapping

When converting Docker-based instructions or mental models to container:

Flags map closely: -d/--detach, --rm, --name, -it/-ti, -e, -v, -p. Always ensure container system start has been run before build/run operations.

Container-Compose command reference

Container-Compose is an optional, third-party tool that adds Compose-style orchestration to Apple Container. It does not ship with container; install it separately with brew install container-compose.

Common flags

• -f, --file <path> — path to the Compose file (default docker-compose.yml)
• -e, --env <path> — path to the environment file (default .env)
• -d, --detach — run services in the background when supported

Notes

• Container-Compose has limited Docker Compose compatibility; unsupported directives

may be ignored or cause errors.

• Service DNS names work best on macOS 26 (Tahoe). On macOS 15 (Sequoia), services may

need to communicate via container IPs.

• Ensure container system start has been run before using container-compose up.

container Troubleshooting Guide

Service will not start

Symptom: No default kernel configured

container system start prompts for kernel installation but hangs in non-interactive shells.

Fix:

container system start --enable-kernel-install

This installs the default Kata Containers kernel automatically.

Symptom: failed to read user input

The start command requires a TTY for the kernel install prompt.

Fix: use --enable-kernel-install or --disable-kernel-install to avoid the prompt.

Symptom: apiserver not responding

Check status:

container system status

Restart the service:

container system stop
container system start --enable-kernel-install

Container cannot be reached from host

1. Confirm the container IP:

   container ls

2. Inside the container, bind the service to 0.0.0.0, not 127.0.0.1. 3. From the host, use the container IP (e.g., http://192.168.64.3). 4. If a local DNS domain is configured, use <container-name>.<domain>.

DNS name does not resolve

1. Verify the domain was created:

   sudo container system dns create test

2. Check /etc/resolver/ contains a file for the domain. 3. Ensure the container name matches the hostname exactly. 4. DNS resolution may require a brief delay after container start.

Build fails or is slow

1. Confirm container system status shows running. 2. The first build pulls the base image and may be slow. 3. Ensure the build context (the . argument) contains the Dockerfile and needed files. 4. For network issues, verify registry access:

   container image pull docker.io/hello-world

Image push fails

1. Log in first:

   container registry login <registry-domain>

2. Tag the image with the full registry path:

   container image tag my-app <registry-domain>/<user>/<repo>:<tag>

3. Check the default registry in ~/.config/container/config.toml if you expect Docker Hub.

General diagnostic checklist

1. which container — CLI installed? 2. container --version — which version? 3. container system status — service running? 4. container list --all — any stuck containers? 5. container image list — expected images present? 6. Run bash <skill-path>/scripts/health-check.sh for an end-to-end smoke test.