From e197fe20528de379e6509133aba8f1915ff624dc Mon Sep 17 00:00:00 2001 From: Aryan Kumar Date: Wed, 10 Jun 2026 18:05:39 -0700 Subject: [PATCH 1/2] Add Apple Container agent skill --- README.md | 8 + skills/apple-container/SKILL.md | 110 ++++++++++ skills/apple-container/metadata.json | 14 ++ skills/apple-container/references/commands.md | 118 +++++++++++ .../references/troubleshooting.md | 188 +++++++++++++++++ .../apple-container/references/workflows.md | 198 ++++++++++++++++++ skills/apple-container/scripts/diagnose.sh | 74 +++++++ 7 files changed, 710 insertions(+) create mode 100644 skills/apple-container/SKILL.md create mode 100644 skills/apple-container/metadata.json create mode 100644 skills/apple-container/references/commands.md create mode 100644 skills/apple-container/references/troubleshooting.md create mode 100644 skills/apple-container/references/workflows.md create mode 100755 skills/apple-container/scripts/diagnose.sh diff --git a/README.md b/README.md index f507e3c9e..669541d2c 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,14 @@ To retain your user data so that it is available should you reinstall later, run - [Build and run](./BUILDING.md) `container` on your own development system. - View the project [API documentation](https://apple.github.io/container/documentation/). +### Agent skill + +Install the `apple-container` agent skill to help coding agents use `container` for Linux development workflows, image builds, networking, and troubleshooting: + +```bash +npx skills add apple/container@apple-container +``` + ## Contributing Contributions to `container` are welcome and encouraged. Please see our [main contributing guide](https://github.com/apple/containerization/blob/main/CONTRIBUTING.md) for more information. diff --git a/skills/apple-container/SKILL.md b/skills/apple-container/SKILL.md new file mode 100644 index 000000000..2953f1843 --- /dev/null +++ b/skills/apple-container/SKILL.md @@ -0,0 +1,110 @@ +--- +name: apple-container +description: Use Apple's `container` CLI for Linux container development on Apple silicon Macs. Trigger when users ask to run Linux commands on macOS, replace Docker Desktop with Apple Container, build or run OCI images, manage Apple container services, volumes, networks, registry auth, port forwarding, container machines, or debug Apple Container networking/service failures. +metadata: + author: apple + version: "1.0.0" +--- + +# Apple Container + +Operate Apple's `container` CLI as a native macOS Linux container runtime for development, build, test, and debugging workflows. + +## First Moves + +1. Confirm the host is eligible before assuming `container` can run: + ```bash + sw_vers + uname -m + command -v container + container --version + ``` + Require Apple silicon (`arm64`) and macOS 26 or newer. +2. If `container` exists, start or verify the service: + ```bash + container system status || container system start + ``` +3. Run a smoke test before using it for real work: + ```bash + container run --rm docker.io/library/alpine:latest sh -lc 'uname -a; nslookup github.com' + ``` +4. For project work, mount the current directory and set `/work`: + ```bash + container run --rm -it -v "$PWD:/work" -w /work docker.io/library/ubuntu:24.04 bash + ``` + +## When To Prefer Apple Container + +- Use it when the user is on an Apple silicon Mac and needs Linux tooling that is missing or awkward on macOS. +- Use it for disposable Linux commands, building OCI images, testing Dockerfiles/Containerfiles, running services with port forwarding, or reproducing Linux-only failures. +- Prefer standard OCI images from registries (`docker.io/library/ubuntu:24.04`, `alpine:latest`, project images) and ordinary `container run` workflows first. +- Use `container machine` only when the user needs a persistent Linux environment. Machine images must boot like a tiny system and provide `/sbin/init`; many minimal distro images are not suitable without customization. +- Avoid assuming Docker CLI compatibility. The command is `container`, not `docker`, and some semantics differ. + +`container` is the CLI/runtime project. It uses Apple's Containerization Swift package for lower-level container, image, and process management. If the user asks to build Swift software directly against those lower-level APIs, consult `apple/containerization`; otherwise stay in this CLI workflow. + +## Core Workflows + +### Disposable Linux shell + +```bash +container run --rm -it -v "$PWD:/work" -w /work docker.io/library/ubuntu:24.04 bash +``` + +### One-shot Linux command + +```bash +container run --rm -v "$PWD:/work" -w /work docker.io/library/alpine:latest sh -lc 'apk --version && ls -la' +``` + +### Build and run an image + +```bash +container build -t local/my-app:dev . +container run --rm -p 8080:8080 local/my-app:dev +``` + +### Long-running service + +```bash +container run -d --name web -p 8080:80 docker.io/library/nginx:latest +container logs -f web +container stop web +container delete web +``` + +### Inspect, copy, and clean up + +```bash +container list --all +container inspect +container cp ./file.txt :/tmp/file.txt +container stats --no-stream +container prune +container image prune +container system df +``` + +## References + +- Read [references/commands.md](references/commands.md) for command groups and feature coverage. +- Read [references/workflows.md](references/workflows.md) for common dev, build, network, volume, registry, and machine patterns. +- Read [references/troubleshooting.md](references/troubleshooting.md) when install, service, DNS, VPN, vmnet, kernel, builder, or machine mode fails. + +## Diagnostic Script + +Run the bundled diagnostic when the environment is unknown or networking behaves strangely: + +```bash +bash skills/apple-container/scripts/diagnose.sh +``` + +From an installed skill path, use the equivalent path under that agent's skills directory. + +## Safety Notes + +- Ask before installing, upgrading, uninstalling, or running commands that require administrator privileges. +- Do not delete containers, images, volumes, or machines unless they were created for the current task or the user explicitly asks for cleanup. +- Stop services gracefully with `container stop` before using `container kill`. +- Treat host bind mounts as real host filesystem access. Mount only the project directory unless the user requests a wider mount. +- If a VPN is active, suspect route collisions or network filtering before changing container configuration. diff --git a/skills/apple-container/metadata.json b/skills/apple-container/metadata.json new file mode 100644 index 000000000..54cc74826 --- /dev/null +++ b/skills/apple-container/metadata.json @@ -0,0 +1,14 @@ +{ + "version": "1.0.0", + "organization": "Apple Container", + "date": "June 2026", + "abstract": "Operational guide for Apple's native `container` CLI on Apple silicon Macs. Helps AI agents install and verify the runtime, run Linux development shells, build and manage OCI images, operate services, networks, volumes, registries, persistent machines, and diagnose vmnet, DNS, VPN, BuildKit, and machine boot failures.", + "references": [ + "https://github.com/apple/container", + "https://github.com/apple/container/blob/main/docs/command-reference.md", + "https://github.com/apple/container/blob/main/docs/how-to.md", + "https://github.com/apple/container/blob/main/docs/container-machine.md", + "https://github.com/apple/container/blob/main/docs/container-system-config.md", + "https://github.com/apple/containerization" + ] +} diff --git a/skills/apple-container/references/commands.md b/skills/apple-container/references/commands.md new file mode 100644 index 000000000..a6fbaf922 --- /dev/null +++ b/skills/apple-container/references/commands.md @@ -0,0 +1,118 @@ +# Apple Container Commands + +Use this as a compact command map. Prefer `container --help` for exact flags on the installed version. + +## System + +- `container system start`: start API server, image service, networking helpers, machine API server, and first-run kernel setup. +- `container system stop`: stop containers and system services. +- `container system status`: show running state, app root, install root, and API server version. +- `container system version`: show component versions. +- `container system logs`: inspect service logs; use this for API server, vmnet, builder, and machine failures. +- `container system df`: show disk usage for images, containers, and volumes. +- `container system dns create|delete|list`: manage local DNS domains. +- `container system kernel set`: set the default kernel. +- `container system property list`: inspect system properties when supported by the installed release. + +System defaults live in `~/.config/container/config.toml`. Top-level sections include `[build]`, `[container]`, `[dns]`, `[kernel]`, `[network]`, `[registry]`, `[vminit]`, and `[plugin.]`. Use config for persistent defaults; use CLI flags for task-local overrides. + +## Run And Build + +- `container run [args...]`: create and run a container, pulling the image if needed. +- `container build [context]`: build an OCI image from a Dockerfile or Containerfile using BuildKit. +- `container builder start|status|stop|delete`: manage the builder container used for image builds. + +Important `run` flags: + +- `--rm`: remove the container after exit. +- `-it`: interactive terminal. +- `-v "$PWD:/work" -w /work`: mount and enter the current project. +- `-p 8080:80`: publish a container port on localhost. +- `--mount type=bind,source=...,target=...,readonly`: explicit bind mount syntax. +- `--cpus 4 --memory 8G`: resource limits. +- `--platform linux/arm64` or `--platform linux/amd64`: choose image platform. +- `--rosetta`: enable Rosetta for compatible amd64 workloads. +- `--ssh`: forward the host SSH agent. +- `--init`: run an init process that forwards signals and reaps processes. +- `--init-image ` and `--kernel `: advanced boot customization. +- `--network [,mac=...][,mtu=...]`: attach a network. +- `--dns`, `--dns-search`, `--no-dns`: override DNS behavior. +- `--cap-add`, `--cap-drop`, `--read-only`, `--tmpfs`, `--shm-size`, `--ulimit`: runtime isolation and process settings. +- `--virtualization`: expose virtualization capabilities to the container when host and guest support it. + +Important `build` flags: + +- `-t, --tag `: tag output image; may be repeated. +- `-f, --file `: choose Dockerfile/Containerfile. +- `--target `: build a named stage. +- `--build-arg key=value`: pass build args. +- `--secret id=...,env=...` or `--secret id=...,src=...`: pass build secrets. +- `--platform os/arch[/variant]`: build for a platform. +- `--pull`, `--no-cache`: control freshness and cache use. +- `--cpus`, `--memory`: resource limits for the builder. +- `--output type=oci|tar|local[,dest=...]`: choose output. + +## Container Lifecycle + +- `container create`: create without starting. +- `container start [-a] [-i] `: start a stopped container. +- `container exec [-it] `: run a command in a running container. +- `container stop [--all] [--signal SIGTERM] [--time 5] `: graceful stop. +- `container kill [--all] [--signal KILL] `: immediate signal. +- `container delete|rm [--all] [--force] `: remove containers. +- `container list|ls [--all] [--format json|yaml|toml|table]`: list containers. +- `container inspect `: inspect containers. +- `container logs [--boot] [--follow] [-n N] `: show stdio or boot logs. +- `container stats [--no-stream] [--format json|yaml|toml|table] [id...]`: resource usage. +- `container copy|cp `: copy between host and running container using `id:/path`. +- `container export [-o file.tar] `: export a stopped container filesystem. +- `container prune`: delete stopped containers. + +## Images + +- `container image pull `: pull from a registry. +- `container image list|ls [-v] [--format json|yaml|toml|table]`: list local images. +- `container image inspect `: inspect images. +- `container image tag `: create another reference. +- `container image push `: push to a registry. +- `container image save -o image.tar `: save image archive. +- `container image load -i image.tar`: load image archive. +- `container image delete|rm [--all] [--force] `: remove images. +- `container image prune [-a]`: remove unused images. + +## Registry + +- `container registry login `: authenticate to a registry. +- `container registry logout `: remove auth. +- `container registry list|ls`: list registry logins. + +`--scheme auto` treats loopback, RFC1918 private IPs, and container DNS-domain hosts as internal/local and uses HTTP; otherwise it uses HTTPS. + +## Network + +- `container network create [--subnet CIDR] [--subnet-v6 CIDR] [--internal] `: create a NAT or host-only network. +- `container network list|ls`: list networks. +- `container network inspect `: inspect subnet, gateway, and mode. +- `container network delete|rm `: remove networks. +- `container network prune`: remove unused networks. + +The built-in `default` network is NAT-backed by vmnet. On macOS, VPNs and network filters can interfere with the VM bridge or route table. + +## Volumes + +- `container volume create `: create a managed volume. +- `container volume list|ls`: list volumes. +- `container volume inspect `: inspect details. +- `container volume delete|rm `: delete volumes. +- `container volume prune`: remove unused volumes. + +Use bind mounts for direct project access; use volumes for runtime data that should not live in the project tree. + +## Machines + +- `container machine create --name [--set-default] [--cpus N] [--memory 8G] [--home-mount rw|ro|none]`: create and boot a persistent Linux machine. +- `container machine run [-n name] -- `: run a command or shell, booting the machine if needed. +- `container machine set -n cpus=4 memory=8G home-mount=ro`: change configuration; restart to apply. +- `container machine list|ls`, `inspect`, `logs`, `stop`, `delete`, `set-default`: manage machines. + +Machine images need a suitable `/sbin/init`. If a plain distro image exits with `/sbin/init: not found` or similar, use a machine-oriented image or build a custom image with a minimal init. diff --git a/skills/apple-container/references/troubleshooting.md b/skills/apple-container/references/troubleshooting.md new file mode 100644 index 000000000..0acf0dc55 --- /dev/null +++ b/skills/apple-container/references/troubleshooting.md @@ -0,0 +1,188 @@ +# Apple Container Troubleshooting + +## Quick Diagnostic Order + +1. Host compatibility: + ```bash + sw_vers + uname -m + ``` +2. CLI and service: + ```bash + command -v container + container --version + container system status + ``` +3. Start/restart services: + ```bash + container system stop + container system start + ``` +4. Network smoke test: + ```bash + container run --rm docker.io/library/alpine:latest sh -lc 'cat /etc/resolv.conf; ping -c 1 -W 3 1.1.1.1; nslookup github.com' + ``` +5. Logs: + ```bash + container system logs --last 200 + container network inspect default + ``` + +## CLI Missing Or Unsupported Host + +Symptoms: + +- `container: command not found` +- install docs do not match host +- service cannot start on Intel or older macOS + +Checks: + +```bash +uname -m +sw_vers -productVersion +``` + +Use Apple silicon (`arm64`) and macOS 26 or newer. If missing, install the latest signed package from Apple's GitHub releases. Ask before running privileged installer commands. + +## First Start Asks For Kernel + +On first `container system start`, the CLI may ask to install the recommended default kernel. Accept it for normal use. If automation fails because the prompt is non-interactive, rerun interactively or pipe a yes only when the user has consented: + +```bash +printf 'Y\n' | container system start +``` + +## Containers Pull But DNS Or Ping Fails + +Symptoms: + +- image pull succeeds +- `nslookup` inside the running container times out +- `ping 1.1.1.1` inside the container fails +- `/etc/resolv.conf` points at a vmnet gateway such as `192.168.64.1` + +Likely causes: + +- VPN route collision with `192.168.64.0/24` +- endpoint security, firewall, or packet filter intercepting vmnet NAT +- custom network subnet still routed through a VPN interface + +Checks: + +```bash +netstat -rn -f inet | grep '192.168.64\|default\|utun' +container network inspect default +container run --rm docker.io/library/alpine:latest sh -lc 'ip route; cat /etc/resolv.conf; nslookup github.com' +``` + +Fixes: + +- Ask the user to temporarily disable VPN/security network filters and retry. +- Restart services after network changes: + ```bash + container system stop + container system start + ``` +- If the default subnet collides, try a custom network: + ```bash + container network create --subnet 192.168.105.0/24 devnet + container run --rm --network devnet docker.io/library/alpine:latest sh -lc 'nslookup github.com' + ``` +- If both default and custom networks fail, do not keep changing app code; gather system logs. + +## `apt-get update` Or Package Manager Hangs + +First check raw container networking. If DNS fails, fix network/VPN first. If DNS works but one mirror hangs, switch mirrors or retry. For Ubuntu on Apple silicon, package URLs normally use `ports.ubuntu.com`. + +## BuildKit Or `container build` Fails + +Checks: + +```bash +container builder status +container builder stop +container builder start +container build --progress plain -t local/test . +``` + +Common fixes: + +- Use `--progress plain` to capture logs. +- Increase builder resources with `--cpus` and `--memory`. +- Use `--no-cache` for cache corruption or stale layer suspicion. +- Check network from a running container if package downloads fail during build. +- Stop/delete the builder if it is wedged: + ```bash + container builder stop + container builder delete + ``` +- If every build needs more resources, set persistent builder defaults in `~/.config/container/config.toml`: + ```toml + [build] + cpus = 4 + memory = "8gb" + ``` + +## Port Publishing Does Not Work + +Checks: + +```bash +container list +container inspect +container logs +lsof -nP -iTCP: -sTCP:LISTEN +``` + +Fixes: + +- Confirm the app listens on `0.0.0.0` inside the container, not only `127.0.0.1`. +- Confirm the `-p host:container` mapping uses the application port. +- Avoid reusing a host port that is already bound. + +## Bind Mount Issues + +Use absolute paths or `$PWD`: + +```bash +container run --rm -v "$PWD:/work" -w /work alpine:latest ls -la +``` + +If files appear read-only, check mount syntax, host permissions, and whether the path is under a macOS-protected location. Do not broaden the mount to the whole home directory unless the user asks. + +## Machine Mode Fails + +Symptoms: + +- `failed to boot container machine` +- `cannot exec: container is not running` +- `/sbin/init: not found` +- `/sbin/openrc: No such file or directory` + +Cause: + +`container machine` expects a machine-like image that can keep running under `/sbin/init`. Plain minimal distro images may exit immediately. + +Fixes: + +- Use an image known to support machine mode. +- Inspect logs: + ```bash + container machine logs + container machine inspect + ``` +- Delete broken experimental machines only after confirming they are not user data: + ```bash + container machine stop + container machine delete + ``` + +## Useful Log Commands + +```bash +container system logs --last 200 +container logs --boot +container logs -f +container machine logs +``` diff --git a/skills/apple-container/references/workflows.md b/skills/apple-container/references/workflows.md new file mode 100644 index 000000000..14d964256 --- /dev/null +++ b/skills/apple-container/references/workflows.md @@ -0,0 +1,198 @@ +# Apple Container Workflows + +## Install Or Upgrade + +1. Verify the host: + ```bash + sw_vers + uname -m + ``` +2. Use the latest signed installer from Apple Container releases. +3. Start services: + ```bash + container system start + container system status + ``` +4. Upgrade with: + ```bash + container system stop + /usr/local/bin/update-container.sh + container system start + ``` + +Installation, upgrade, downgrade, and uninstall may require administrator privileges. Ask the user before running privileged commands. + +## Replace A Docker-Style Dev Shell + +```bash +container run --rm -it \ + -v "$PWD:/work" \ + -w /work \ + docker.io/library/ubuntu:24.04 \ + bash +``` + +Then install temporary tools inside the disposable shell: + +```bash +apt-get update +apt-get install -y build-essential git curl python3 python3-pip +``` + +For repeated use, create a project Dockerfile and build a local image: + +```Dockerfile +FROM docker.io/library/ubuntu:24.04 +RUN apt-get update && apt-get install -y --no-install-recommends \ + build-essential ca-certificates curl git python3 python3-pip \ + && rm -rf /var/lib/apt/lists/* +WORKDIR /work +CMD ["bash"] +``` + +```bash +container build -t local/project-dev:latest . +container run --rm -it -v "$PWD:/work" -w /work local/project-dev:latest +``` + +## Run A Web Service + +```bash +container run -d --name app -p 3000:3000 -v "$PWD:/work" -w /work local/app:dev +container logs -f app +curl http://localhost:3000 +container stop app +container delete app +``` + +Use `container inspect app` when port publishing or IP allocation is unclear. + +## Access Host Services From A Container + +Try the container network gateway as the host-side address: + +```bash +container network inspect default +container run --rm docker.io/library/alpine:latest sh -lc 'ip route; nc -vz 192.168.64.1 5432' +``` + +If the host service binds only to `127.0.0.1`, configure it to listen on the appropriate host interface or use a published socket/workflow supported by the service. + +## Use Host SSH Credentials + +```bash +container run --rm -it --ssh -v "$PWD:/work" -w /work docker.io/library/ubuntu:24.04 bash +``` + +Prefer `--ssh` over copying private keys into containers. + +## Use Volumes + +```bash +container volume create node-cache +container run --rm -it \ + -v "$PWD:/work" \ + --mount type=volume,source=node-cache,target=/root/.npm \ + -w /work \ + local/project-dev:latest +``` + +Use `container volume inspect`, `container volume list`, and `container volume prune` for maintenance. + +## Custom Networks + +Create custom networks for isolation or subnet conflicts: + +```bash +container network create --subnet 192.168.105.0/24 devnet +container run --rm --network devnet docker.io/library/alpine:latest sh +container network inspect devnet +``` + +If traffic fails on custom and default networks, suspect host VPN, endpoint security, firewall, or macOS vmnet routing before changing application code. + +To change default subnets for newly-created networks, edit `~/.config/container/config.toml`: + +```toml +[network] +subnet = "192.168.100.0/24" +subnetv6 = "fd00:abcd::/64" +``` + +Restart services after changing system config: + +```bash +container system stop +container system start +``` + +## Registry Auth And Image Transfer + +```bash +container registry login ghcr.io +container build -t ghcr.io/OWNER/IMAGE:tag . +container image push ghcr.io/OWNER/IMAGE:tag +container image save -o image.tar ghcr.io/OWNER/IMAGE:tag +container image load -i image.tar +``` + +Do not put tokens directly in command arguments when an environment variable or registry login flow is available. + +## Persistent Container Machines + +Use machines for long-lived Linux environments: + +```bash +container machine create alpine:3.22 --name devbox --set-default --cpus 4 --memory 8G --home-mount rw +container machine run -n devbox -- uname -a +container machine run -n devbox +container machine stop devbox +``` + +Machine caveats: + +- The image must boot with a valid `/sbin/init`. +- Config changes via `container machine set` apply after restart. +- Prefer `home-mount=ro` when the task does not require writing into the user's home directory. +- Use `container machine logs ` when boot or exec hangs. + +## Rosetta And Platforms + +Apple silicon is `arm64`; prefer native arm64 images. For x86_64-only tools: + +```bash +container run --rm --platform linux/amd64 --rosetta docker.io/library/ubuntu:24.04 uname -m +``` + +If an image has both arm64 and amd64 variants, use `--platform` only when the requested architecture matters. + +To change persistent defaults, use `~/.config/container/config.toml`: + +```toml +[container] +cpus = 4 +memory = "4gb" + +[build] +cpus = 4 +memory = "8gb" +rosetta = true + +[registry] +domain = "docker.io" +``` + +## Cleanup + +After experiments: + +```bash +container list --all +container prune +container image prune +container volume prune +container network prune +container system df +``` + +Do not prune globally in a user's active development environment without asking. diff --git a/skills/apple-container/scripts/diagnose.sh b/skills/apple-container/scripts/diagnose.sh new file mode 100755 index 000000000..566680d3a --- /dev/null +++ b/skills/apple-container/scripts/diagnose.sh @@ -0,0 +1,74 @@ +#!/bin/bash +# Copyright © 2026 Apple Inc. and the container project authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +set -u + +section() { + printf '\n== %s ==\n' "$1" +} + +run() { + printf '$ %s\n' "$*" + "$@" 2>&1 || true +} + +section "Host" +run sw_vers +run uname -m + +section "Container CLI" +if ! command -v container >/dev/null 2>&1; then + echo "container CLI not found on PATH" + exit 0 +fi +run container --version + +section "System Status" +run container system status + +section "Networks" +run container network list +run container network inspect default + +section "Host Routes" +netstat -rn -f inet 2>/dev/null | grep -E 'default|192\.168\.64|utun|bridge' || true + +section "Container Network Smoke Test" +container run --rm docker.io/library/alpine:latest sh -lc ' + echo "--- /etc/resolv.conf ---" + cat /etc/resolv.conf + echo "--- route ---" + (ip route 2>/dev/null || route -n 2>/dev/null || true) + echo "--- ping gateway ---" + ping -c 1 -W 3 "$(awk "/nameserver/ {print \$2; exit}" /etc/resolv.conf)" 2>&1 || true + echo "--- ping public ip ---" + ping -c 1 -W 3 1.1.1.1 2>&1 || true + echo "--- dns ---" + nslookup github.com 2>&1 || true +' || true + +section "Recent System Logs" +container system logs --last 80 2>&1 | tail -80 || true + +cat <<'EOF' + +If images pull but ping/DNS fails inside containers, check for VPN or endpoint +security routes that overlap 192.168.64.0/24 or block vmnet NAT. Try disabling +the VPN, then run: + + container system stop + container system start + container run --rm docker.io/library/alpine:latest sh -lc 'nslookup github.com' +EOF From b4bcf1f58529f373f75f1868b677ff760946f1aa Mon Sep 17 00:00:00 2001 From: aryan5v Date: Fri, 12 Jun 2026 10:12:16 -0700 Subject: [PATCH 2/2] Add installation instructions and doc links to apple-container skill The skill assumed `container` was already installed and had no concrete setup path. Add install guidance across SKILL.md, the workflows and troubleshooting references, and the diagnostic script: - Homebrew (`brew install container`) as the simplest path. - Apple's signed `.pkg` installer as the fallback when Homebrew is absent, including the official double-click flow and a headless `installer` equivalent for agents driving a terminal. - Upgrade/downgrade/uninstall helper scripts under /usr/local. - First-run `container system start` and verification steps. - Note that `brew install container` can succeed on macOS 15 even though the runtime needs macOS 26, so a clean install is not proof the host is supported. Link the user guide (apple.github.io/container/documentation), the Homebrew formula page, and the releases page from SKILL.md and metadata.json. --- skills/apple-container/SKILL.md | 62 +++++++++++++++++-- skills/apple-container/metadata.json | 3 + .../references/troubleshooting.md | 15 ++++- .../apple-container/references/workflows.md | 33 ++++++++-- skills/apple-container/scripts/diagnose.sh | 10 +++ 5 files changed, 112 insertions(+), 11 deletions(-) diff --git a/skills/apple-container/SKILL.md b/skills/apple-container/SKILL.md index 2953f1843..60571ce1a 100644 --- a/skills/apple-container/SKILL.md +++ b/skills/apple-container/SKILL.md @@ -19,20 +19,74 @@ Operate Apple's `container` CLI as a native macOS Linux container runtime for de command -v container container --version ``` - Require Apple silicon (`arm64`) and macOS 26 or newer. -2. If `container` exists, start or verify the service: + Require Apple silicon (`arm64`) and macOS 26 (Tahoe) or newer. The runtime relies on + macOS 26 virtualization and networking APIs; older macOS is not supported for real use. +2. If `container` is not installed, install it (see [Install](#install)). Ask before running + privileged steps, since the installer writes under `/usr/local` and needs an admin password. +3. Once `container` exists, start or verify the service: ```bash container system status || container system start ``` -3. Run a smoke test before using it for real work: +4. Run a smoke test before using it for real work: ```bash container run --rm docker.io/library/alpine:latest sh -lc 'uname -a; nslookup github.com' ``` -4. For project work, mount the current directory and set `/work`: +5. For project work, mount the current directory and set `/work`: ```bash container run --rm -it -v "$PWD:/work" -w /work docker.io/library/ubuntu:24.04 bash ``` +## Install + +Use Homebrew when available; it is the least error-prone path and keeps `container` upgradable +with the user's other tooling: + +```bash +brew install container +``` + +If Homebrew is not installed, use Apple's signed installer rather than installing Homebrew just for +this. The official steps: + +1. Download the latest signed installer package for `container` from the + [GitHub release page](https://github.com/apple/container/releases). +2. Double-click the package file and follow the instructions. +3. Enter the administrator password when prompted, so the installer can place files under + `/usr/local`. + +When driving this from the terminal without a GUI, run the same package non-interactively (ask the +user before the privileged step): + +```bash +# After downloading container--installer-signed.pkg to the current directory: +sudo installer -pkg ./container-*-installer-signed.pkg -target / +``` + +The installer places files under `/usr/local` and bundles helper scripts: + +```bash +/usr/local/bin/update-container.sh # upgrade in place +/usr/local/bin/update-container.sh -v 0.3.0 # pin a specific version (downgrade) +/usr/local/bin/uninstall-container.sh -k # uninstall, keep user data +/usr/local/bin/uninstall-container.sh -d # uninstall, delete all data +``` + +After installing, initialize and verify the runtime: + +```bash +container system start # first run may prompt to install the recommended kernel; accept it +container system status +container --version +``` + +Note: `brew install container` succeeds on macOS 15 (Sequoia), but the runtime is only supported +on macOS 26 (Tahoe) or newer — a clean install does not by itself prove the host can run +containers. Always confirm the macOS version from step 1 before relying on it. + +Docs: [installation & user guide](https://apple.github.io/container/documentation/) · +[Homebrew formula](https://formulae.brew.sh/formula/container) · +[GitHub project](https://github.com/apple/container) + ## When To Prefer Apple Container - Use it when the user is on an Apple silicon Mac and needs Linux tooling that is missing or awkward on macOS. diff --git a/skills/apple-container/metadata.json b/skills/apple-container/metadata.json index 54cc74826..8a48e5f78 100644 --- a/skills/apple-container/metadata.json +++ b/skills/apple-container/metadata.json @@ -5,6 +5,9 @@ "abstract": "Operational guide for Apple's native `container` CLI on Apple silicon Macs. Helps AI agents install and verify the runtime, run Linux development shells, build and manage OCI images, operate services, networks, volumes, registries, persistent machines, and diagnose vmnet, DNS, VPN, BuildKit, and machine boot failures.", "references": [ "https://github.com/apple/container", + "https://apple.github.io/container/documentation/", + "https://formulae.brew.sh/formula/container", + "https://github.com/apple/container/releases", "https://github.com/apple/container/blob/main/docs/command-reference.md", "https://github.com/apple/container/blob/main/docs/how-to.md", "https://github.com/apple/container/blob/main/docs/container-machine.md", diff --git a/skills/apple-container/references/troubleshooting.md b/skills/apple-container/references/troubleshooting.md index 0acf0dc55..ca3063feb 100644 --- a/skills/apple-container/references/troubleshooting.md +++ b/skills/apple-container/references/troubleshooting.md @@ -43,7 +43,20 @@ uname -m sw_vers -productVersion ``` -Use Apple silicon (`arm64`) and macOS 26 or newer. If missing, install the latest signed package from Apple's GitHub releases. Ask before running privileged installer commands. +Use Apple silicon (`arm64`) and macOS 26 or newer. If the CLI is missing, install it (ask before +the privileged step): + +```bash +brew install container # simplest, if Homebrew is present +# otherwise, install Apple's signed .pkg from https://github.com/apple/container/releases: +sudo installer -pkg ./container-*-installer-signed.pkg -target / +container system start +``` + +If the service refuses to start on Intel or on macOS earlier than 26, the host is unsupported — +`brew install container` can still succeed on macOS 15, so a successful install is not proof the +host can run containers. Stop here and tell the user rather than working around it. Full setup +guide: https://apple.github.io/container/documentation/ ## First Start Asks For Kernel diff --git a/skills/apple-container/references/workflows.md b/skills/apple-container/references/workflows.md index 14d964256..a8486849a 100644 --- a/skills/apple-container/references/workflows.md +++ b/skills/apple-container/references/workflows.md @@ -2,25 +2,46 @@ ## Install Or Upgrade -1. Verify the host: +1. Verify the host. Apple silicon (`arm64`) and macOS 26 (Tahoe) or newer are required for real use: ```bash sw_vers uname -m ``` -2. Use the latest signed installer from Apple Container releases. -3. Start services: +2. Install. Homebrew is the simplest path: ```bash - container system start + brew install container + ``` + If Homebrew is unavailable, use Apple's signed installer (the official steps): + - Download the latest signed installer package from https://github.com/apple/container/releases. + - Double-click the package and follow the instructions. + - Enter the administrator password when prompted, so files can be placed under `/usr/local`. + + To do the same from a terminal without a GUI (admin password required): + ```bash + sudo installer -pkg ./container-*-installer-signed.pkg -target / + ``` +3. Start and verify services: + ```bash + container system start # first run may offer to install the default kernel; accept it container system status + container --version ``` -4. Upgrade with: +4. Upgrade with the bundled helper (installed under `/usr/local`): ```bash container system stop /usr/local/bin/update-container.sh container system start ``` +5. Uninstall when asked: + ```bash + /usr/local/bin/uninstall-container.sh -k # keep user data (images, volumes, machines) + /usr/local/bin/uninstall-container.sh -d # delete all data + ``` + With Homebrew, `brew uninstall container` removes the CLI; data under `~/.config/container` + and the application data root persists unless you remove it explicitly. -Installation, upgrade, downgrade, and uninstall may require administrator privileges. Ask the user before running privileged commands. +Installation, upgrade, downgrade, and uninstall may require administrator privileges. Ask the user +before running privileged commands. Reference: https://apple.github.io/container/documentation/ ## Replace A Docker-Style Dev Shell diff --git a/skills/apple-container/scripts/diagnose.sh b/skills/apple-container/scripts/diagnose.sh index 566680d3a..092a92ad0 100755 --- a/skills/apple-container/scripts/diagnose.sh +++ b/skills/apple-container/scripts/diagnose.sh @@ -31,6 +31,16 @@ run uname -m section "Container CLI" if ! command -v container >/dev/null 2>&1; then echo "container CLI not found on PATH" + echo + echo "Install it (ask before the privileged step):" + echo " brew install container # if Homebrew is present" + echo " # otherwise install Apple's signed .pkg from:" + echo " # https://github.com/apple/container/releases" + echo " # sudo installer -pkg ./container-*-installer-signed.pkg -target /" + echo " container system start" + echo + echo "Requires Apple silicon and macOS 26 (Tahoe) or newer." + echo "Docs: https://apple.github.io/container/documentation/" exit 0 fi run container --version