Guide for using Apple Container CLI to run Linux containers on Apple silicon Macs (macOS 26+). Use when managing OCI containers, building images, configuring networks/volumes, or working with container system services on macOS.
Manages Linux containers on Apple silicon Macs using the native Apple Container CLI for OCI images, networking, and volumes.
npx claudepluginhub vinnie357/claude-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/command-reference.mdscripts/container-cleanup.nuscripts/container-images.nuscripts/container-lifecycle.nuscripts/container-system.nutemplates/0.4.1/commands.mdtemplates/0.5.0/commands.mdtemplates/0.6.0/commands.mdtemplates/0.7.0/commands.mdtemplates/0.8.0/commands.mdtemplates/0.9.0/commands.mdtemplates/mise.tomlThis skill activates when working with Apple Container for running Linux containers natively on Apple silicon Macs.
Activate when:
Apple Container is a macOS-native tool for running Linux containers as lightweight virtual machines on Apple silicon:
.pkg from GitHub releasesManage the container system service that runs in the background:
# Start the system service
container system start
# Stop the system service
container system stop
# Check service status
container system status
# Show CLI version
container system version
# View system logs
container system logs
# Show disk usage
container system df
Configure system-level settings (consolidated in 0.5.0):
# List all properties
container system property list
# Get a specific property
container system property get <key>
# Set a property
container system property set <key> <value>
# Clear a property
container system property clear <key>
Manage DNS configuration for containers:
# Create a DNS entry
container system dns create <name> <ip>
# Delete a DNS entry
container system dns delete <name>
# List DNS entries
container system dns list
Set a custom Linux kernel for containers:
# Set custom kernel
container system kernel set <path>
# Force set (0.5.0+)
container system kernel set --force <path>
# Run interactively
container run -it ubuntu:latest /bin/bash
# Run detached
container run -d --name myapp nginx:latest
# Run with port mapping
container run -d -p 8080:80 nginx:latest
# Run with volume mount
container run -v /host/path:/container/path ubuntu:latest
# Run with environment variables
container run -e FOO=bar -e BAZ=qux myimage:latest
# Run with auto-remove
container run --rm -it alpine:latest /bin/sh
# Combined common flags
container run -d --name web -p 8080:80 -v ./html:/usr/share/nginx/html -e ENV=prod nginx:latest
# Run with resource limits (0.9.0+)
container run -d --name app --cpus 2 --memory 4g myapp:latest
# Run with read-only rootfs (0.8.0+)
container run --read-only -v tmpdata:/tmp myapp:latest
# Run with Rosetta x86_64 emulation (0.7.0+)
container run --rosetta -it amd64-image:latest /bin/bash
# Run with DNS configuration
container run --dns 8.8.8.8 --dns-search example.com myapp:latest
# Run with custom MAC address (0.7.0+)
container run --mac-address 02:42:ac:11:00:02 --network mynet myapp:latest
# Access host from container (0.9.0+)
# Use host.docker.internal to reach host services
container run -e API_URL=http://host.docker.internal:3000 myapp:latest
# List running containers
container list
container ls
# List all containers (including stopped)
container list --all
# Start a stopped container
container start <name-or-id>
# Stop a running container
container stop <name-or-id>
# Kill a container (force stop)
container kill <name-or-id>
# Remove a container
container delete <name-or-id>
container rm <name-or-id>
# Execute command in running container
container exec -it <name-or-id> /bin/bash
# Execute command detached (0.7.0+)
container exec -d <name-or-id> /usr/bin/background-task
# View container logs
container logs <name-or-id>
container logs --follow <name-or-id>
# Inspect container details
container inspect <name-or-id>
# Container resource stats
container stats
# Remove all stopped containers
container prune
# Create container without starting
container create --name myapp nginx:latest
# Start it later
container start myapp
# Pull an image
container image pull ubuntu:latest
# Pull with platform specification
container image pull --platform linux/arm64 nginx:latest
container image pull --arch arm64 --os linux nginx:latest
# List images
container image list
container image ls
# Tag an image
container image tag ubuntu:latest myregistry/ubuntu:v1
# Push to registry
container image push myregistry/ubuntu:v1
# Save image to archive
container image save ubuntu:latest -o ubuntu.tar
# Load image from archive
container image load -i ubuntu.tar
# Delete an image
container image delete ubuntu:latest
# Force delete an image (0.9.0+, verify flag with --help)
container image delete --force ubuntu:latest
# Inspect image metadata (enhanced output in 0.9.0+)
container image inspect ubuntu:latest
# Remove unused images
container image prune
# Remove all unused images, not just dangling (0.7.0+)
container image prune -a
When pulling or building images, specify the target platform:
--platform linux/arm64 # Full platform string
--arch arm64 # Architecture only
--os linux # OS only
--scheme oci # Image scheme
Architecture aliases (0.8.0+): amd64=x86_64, arm64=aarch64
Build OCI-compatible images from Dockerfiles or Containerfiles:
# Build from current directory
container build -t myimage:latest .
# Build with specific Dockerfile
container build -t myimage:latest -f Dockerfile.prod .
# Build with build arguments
container build -t myimage:latest --build-arg VERSION=1.0 .
# Build without cache
container build -t myimage:latest --no-cache .
# Multi-stage build with target
container build -t myimage:latest --target builder .
# Build with platform
container build -t myimage:latest --platform linux/arm64 .
# Build with output
container build -t myimage:latest -o type=local,dest=./output .
# Build with multiple tags (0.6.0+)
container build -t myimage:latest -t myimage:v1.0 .
# Build with no network access (0.6.0+)
container build -t myimage:latest --network none .
# Build with DNS configuration (0.9.0+)
container build -t myimage:latest --dns 8.8.8.8 .
# Build from stdin (0.7.0+)
container build -t myimage:latest -f - . <<EOF
FROM alpine:latest
RUN echo "hello"
EOF
Note: When no Dockerfile is found, the builder falls back to Containerfile (0.6.0+).
The builder runs as a separate process:
# Start the builder
container builder start
# Stop the builder
container builder stop
# Delete the builder
container builder delete
# Check builder status
container builder status
Create and manage container networks:
# Create a network
container network create mynetwork
# Create with subnet
container network create --subnet 10.0.0.0/24 mynetwork
# Create with labels
container network create --labels env=dev mynetwork
# List networks
container network list
# Inspect a network
container network inspect mynetwork
# Delete a network
container network delete mynetwork
# Remove unused networks
container network prune
Network capabilities (0.8.0+): Full IPv6 support. Host-only and isolated network modes available in 0.9.0+ (verify flag syntax with container network create --help).
# Create a shared network
container network create app-net
# Run containers on the network
container run -d --name db --network app-net postgres:latest
container run -d --name web --network app-net -p 8080:80 myapp:latest
# Containers can reach each other by name
container exec web curl http://db:5432
Create and manage persistent volumes:
# Create a volume
container volume create mydata
# Create with size limit
container volume create -s 10G mydata
# Create with labels
container volume create --label env=prod mydata
# Create with driver options
container volume create --opt type=tmpfs mydata
# List volumes
container volume list
# Inspect a volume
container volume inspect mydata
# Delete a volume
container volume delete mydata
# Remove unused volumes
container volume prune
# Mount a named volume
container run -v mydata:/data myimage:latest
# Mount a host directory (bind mount)
container run -v /host/path:/container/path myimage:latest
# Read-only mount
container run -v mydata:/data:ro myimage:latest
Authenticate with container registries:
# Log in to a registry
container registry login <registry-url>
# Log out from a registry
container registry logout <registry-url>
Note: In 0.5.0, the keychain ID changed from com.apple.container to com.apple.container.registry. Re-login is required after upgrading from 0.4.x.
| Version | Change | Migration |
|---|---|---|
| 0.6.0 | Image store directory moved from .build to builder | Update paths referencing .build |
| 0.7.0 | --disable-progress-updates removed | Use --progress none|ansi instead |
| 0.8.0 | Client API reorganization | Update API consumers |
| 0.8.0 | Subnet allocation defaults changed | Review network configurations |
0.6.0: Multiple --tag on build, --network none, network create --subnet, anonymous volumes, volume prune, Containerfile fallback, DNS list --format/--quiet
0.7.0: --rosetta flag, image download progress, stdio save/load, Dockerfile from stdin, container stats, port range publishing, --mac-address, system df, image prune -a, exec -d (detached), network creationDate
0.8.0: --read-only for run/create, architecture aliases (amd64/arm64/x86_64/aarch64), network prune, full IPv6, volume relative paths, env vars from named pipes, CVE-2026-20613 fix
0.9.0: Resource limits (--cpus/--memory), host.docker.internal, host-only/isolated networks, --dns on build, --force on image delete, zstd compression, container prune improvements, enhanced image inspection, Kata 3.26.0 kernel
--disable-progress-updates with --progress none in scripts.build directory to builder| Version | Containerization | Other |
|---|---|---|
| 0.5.0 | 0.9.1 | Builder shim 0.6.1 |
| 0.6.0 | 0.12.1 | |
| 0.7.0 | 0.16.0 | Builder shim 0.7.0 |
| 0.8.0 | 0.21.1 | |
| 0.9.0 | 0.24.0 | Kata 3.26.0 |
See templates/<version>/commands.md for version-specific details (0.4.1, 0.5.0, 0.6.0, 0.7.0, 0.8.0, 0.9.0).
This skill includes focused Nushell scripts for container management:
System service management with health checks:
# Start system service
nu scripts/container-system.nu start
# Check status
nu scripts/container-system.nu status
# Full health check (status + disk + container count)
nu scripts/container-system.nu health
# View disk usage
nu scripts/container-system.nu df
# Show version
nu scripts/container-system.nu version
Image lifecycle operations:
# List images
nu scripts/container-images.nu list
# Pull an image
nu scripts/container-images.nu pull ubuntu:latest
# Build from Dockerfile
nu scripts/container-images.nu build -t myimage:latest .
# Prune unused images
nu scripts/container-images.nu prune
Container run/stop/exec/logs:
# List running containers
nu scripts/container-lifecycle.nu ps
# Run a container
nu scripts/container-lifecycle.nu run ubuntu:latest
# View logs
nu scripts/container-lifecycle.nu logs mycontainer
# Execute command
nu scripts/container-lifecycle.nu exec mycontainer /bin/bash
Prune and disk usage:
# Prune everything unused
nu scripts/container-cleanup.nu prune-all
# Prune only containers
nu scripts/container-cleanup.nu prune-containers
# Show disk usage
nu scripts/container-cleanup.nu df
Copy templates/mise.toml to add container management tasks to any project:
mise container:start # Start system service
mise container:stop # Stop system service
mise container:status # Show formatted status
mise container:run # Run container (accepts image arg)
mise container:ps # List running containers
mise container:images # List images
mise container:build # Build from Dockerfile/Containerfile
mise container:prune # Clean up unused resources
mise container:health # System status + disk + container count
mise container:df # Disk usage
mise container:version # CLI version
# Start the system
container system start
# Pull and run an image
container run -it --rm ubuntu:latest /bin/bash
# Check what's running
container ls
# Build your image
container build -t myapp:latest .
# Run it
container run -d --name myapp -p 8080:80 myapp:latest
# Check logs
container logs --follow myapp
# Create network
container network create mynet
# Start database
container run -d --name postgres --network mynet \
-e POSTGRES_PASSWORD=secret \
-v pgdata:/var/lib/postgresql/data \
postgres:16
# Start application
container run -d --name app --network mynet \
-p 3000:3000 \
-e DATABASE_URL=postgres://postgres:secret@postgres:5432/mydb \
myapp:latest
# Create a volume
container volume create appdata
# Run with volume
container run -d --name db -v appdata:/var/lib/data mydb:latest
# Volume persists after container removal
container rm db
container run -d --name db2 -v appdata:/var/lib/data mydb:latest
# Check status
container system status
# Start if not running
container system start
# View logs for errors
container system logs
# Check system is running
container system status
# Try with explicit platform
container image pull --platform linux/arm64 <image>
# Check registry authentication
container registry login <registry>
# Check volume exists
container volume list
# Inspect volume for mount details
container volume inspect <name>
# Run container with specific user
container run -u 1000:1000 -v myvol:/data myimage:latest
# Check builder status
container builder status
# Restart builder
container builder stop
container builder start
# Delete and recreate if stuck
container builder delete
container builder start
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
This skill should be used when the user wants to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.