container

What this skill does

# Apple Container CLI

This skill activates when working with Apple Container for running Linux containers natively on Apple silicon Macs.

## When to Use This Skill

Activate when:
- Running Linux containers on macOS 26+ with Apple silicon
- Managing container lifecycle (run, stop, exec, logs, inspect)
- Building OCI-compatible container images
- Managing container images (pull, push, tag, save, load)
- Configuring container networks and volumes
- Managing the container system service
- Migrating between Apple Container versions (0.5.x to 0.12.x)

## What is Apple Container?

Apple Container is a macOS-native tool for running Linux containers as lightweight virtual machines on Apple silicon:

- **Swift-based**: Built on Apple's Virtualization.framework
- **OCI-compatible**: Produces and runs standard OCI container images
- **Apple silicon only**: Requires Apple silicon Mac (M1 or later)
- **Pre-1.0**: Currently at version 0.12.3, breaking changes expected between minor versions
- **Lightweight VMs**: Each container runs as a lightweight Linux VM

## Prerequisites

- macOS 26 or later (Tahoe)
- Apple silicon Mac (M1, M2, M3, M4 series)
- Install via signed `.pkg` from [GitHub releases](https://github.com/apple/container/releases)

## System Management

Manage the container system service that runs in the background:

```bash
# Start the system service
container system start

# Stop the system service
container system stop

# Check service status
container system status

# Check service status with format (0.10.0+)
container system status --format json

# Show CLI version
container system version

# View system logs
container system logs

# Show disk usage
container system df
```

### System Properties

Configure system-level settings (consolidated in 0.5.0):

```bash
# 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>
```

Configurable default CPU/memory properties (0.11.0+):

| Property | Description |
|----------|-------------|
| `container.cpus` | Default CPU count for new containers |
| `container.memory` | Default memory for new containers |
| `build.cpus` | Default CPU count for image builds |
| `build.memory` | Default memory for image builds |

### System DNS

Manage DNS configuration for containers:

```bash
# 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
```

### Custom Kernel

Set a custom Linux kernel for containers:

```bash
# Set custom kernel
container system kernel set <path>

# Force set (0.5.0+)
container system kernel set --force <path>
```

## Container Lifecycle

### Run Containers

```bash
# 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

# Run with custom init image (0.10.0+)
container run --init-image custom-init:latest -d --name app myapp:latest

# Run with runtime selection (0.10.0+)
container run --runtime myruntime -d --name app myapp:latest

# Run with init process (0.11.0+)
container run --init -d --name app myapp:latest

# Run with reduced/custom capabilities (0.12.0+)
container run --cap-add NET_ADMIN myimage:latest
container run --cap-drop ALL --cap-add NET_BIND_SERVICE myimage:latest
```

### Manage Running Containers

```bash
# 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
```

### Export Container (0.10.0+)

```bash
# Create an image from a running container (0.10.0+: running; 0.11.0+: stopped containers also supported)
container export <name-or-id> -o exported.tar

# Export with a tag
container export <name-or-id> -t myimage:snapshot
```

### Create Without Starting

```bash
# Create container without starting
container create --name myapp nginx:latest

# Start it later
container start myapp
```

## Image Management

```bash
# 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
```

### Platform Flags

When pulling or building images, specify the target platform:

```bash
--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`

**Default platform (0.11.0+)**: Set `CONTAINER_DEFAULT_PLATFORM` to avoid specifying `--platform` on every pull/build:

```bash
export CONTAINER_DEFAULT_PLATFORM=linux/arm64
```

## Build

Build OCI-compatible images from Dockerfiles or Containerfiles:

```bash
# 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