apple-container-skill（Apple container 技能）

Apple Container Skill

To use the Apple Container CLI, execute the commands below using the run_shell_command tool. Note: This CLI is specific to Apple's container implementation.

Common Workflows & Architecture

These patterns represent best practices for using the Apple Container CLI effectively.

1. System Lifecycle Management

Unlike standard Docker Desktop, the container system services are explicit.

• Startup: Always verify container system status before running operations. If stopped, run container system start.
• Kernel: On first run, system start may prompt to install a Linux kernel. The agent should be aware of this initialization step.
• Cleanup: To save resources when not in use, run container system stop.

2. Networking & Connectivity

• DNS: For stable service discovery, configure a local domain:

1. sudo container system dns create <domain> (e.g., test) 2. container system property set dns.domain <domain> 3. Access containers via http://<container-name>.<domain>.

• Inter-Container: Containers are on a vmnet. Direct IP communication (192.168.64.x) works but can be fragile due to isolation.
• Host Gateway Strategy (Reliable Fallback):

- Standard Method: Use host.docker.internal to connect to services running on the host (macOS). This is the preferred and most portable method. - Manual Method: If for some reason the hostname fails, you can use the Host Gateway IP (192.168.64.1). - *Note:* Disable SSL (sslmode=disable) if connection resets occur via the gateway.

• Localhost: Port forwarding (-p 8080:80) works as expected for accessing containers from the host.

3. Data Persistence

• Volume Initialization: New volumes may contain a lost+found directory, which can cause "directory not empty" errors.
• Best Practice: Always configure services (like PostgreSQL) to use a subdirectory within the volume.

- *Example:* PGDATA=/var/lib/postgresql/data/pgdata instead of the root mount point.

4. Development Patterns

• Git/SSH: Use the --ssh flag (container run --ssh...) to forward the host's SSH agent. This is the preferred method for cloning private repositories inside containers.
• Hot Reloading: Use --volume (e.g., -v $(pwd):/app) to mount source code for immediate feedback, just like standard Docker.
• Builder Tuning: The build process runs in its own VM. For large builds, explicitly scale the builder: container builder start --cpus 4 --memory 8g.

Critical Setup

Before running containers, the system services usually need to be running.

• Check Status: container system status
• Start Services: container system start (may require sudo if installing kernel/root components, but usually run as user)

Commands

System Management

• container system start: Starts the container services.

- Options: --enable-kernel-install, --disable-kernel-install, --app-root <path>, --install-root <path>.

• container system stop: Stops the container services.

- Options: --prefix <string>, --all-domains (stops services in all launchd domains).

• container system status: Checks if services are running.

- Options: --format <format> (e.g., json).

• container system version: Shows CLI and API server versions.
• container system logs: Displays system logs.

- Options: --follow, --last <time> (e.g., 5m, 1h).

• container system df: Shows disk usage.
• container system dns create <domain>: Creates a local DNS domain (requires sudo).
• container system dns list: Lists configured local DNS domains.
• container system dns delete <domain>: Deletes a local DNS domain (requires sudo).
• container system property list: Lists system properties (config).
• container system property get <id>: Gets a system property value.
• container system property set <id> <value>: Sets a system property.

- Examples: container system property set dns.domain my.local

• container system property clear <id>: Resets a system property to default.
• container system kernel set: Installs/updates the Linux kernel.

- Options: --recommended, --arch <arch>, --binary <path>.

Container Lifecycle

• container run [OPTIONS] IMAGE [COMMAND] [ARG...]: Runs a command in a new container.

- Common Options: - -d, --detach: Run in background. - -i, --interactive: Keep STDIN open. - -t, --tty: Allocate a pseudo-TTY. - -p, --publish <host-port:container-port>: Publish a port. - -v, --volume <host-path:container-path>: Mount a volume. - --name <string>: Assign a name. - --rm: Remove after stop. - -e, --env <key=value>: Set environment variable. - -u, --user <user>: Set user (name|uid[:gid]). - -w, --workdir <dir>: Set working directory. - -c, --cpus <count>: CPU limit. - -m, --memory <size>: Memory limit (e.g., 512M, 2G). - --init: Run an init process inside the container. - --init-image <image>: Specify a custom init filesystem image. - --read-only: Mount the container's root filesystem as read-only. - --ulimit <type=soft:hard>: Set ulimits.

• container create [OPTIONS] IMAGE [ARG...]: Creates a container without starting it (same options as run).
• container start [OPTIONS] CONTAINER...: Starts stopped containers.

- Options: -a, --attach, -i, --interactive.

• container stop [OPTIONS] CONTAINER...: Stops running containers.

- Options: -t, --time <seconds> (wait before kill), -s, --signal <signal>.

• container kill [OPTIONS] CONTAINER...: Kills containers immediately.

- Options: -s, --signal <signal>.

• container delete [OPTIONS] CONTAINER...: Deletes containers (aliases: rm).

- Options: -f, --force (delete even if running).

• container exec [OPTIONS] CONTAINER COMMAND [ARG...]: Executes a command in a running container.

- Options: -it, -d, -w, -e, -u, --user.

• container list [OPTIONS]: Lists containers (aliases: ls, ps).

- Options: -a, --all (show stopped too), -q (quiet, IDs only).

• container inspect CONTAINER...: JSON details of containers.
• container logs [OPTIONS] CONTAINER: Fetches container logs.

- Options: -f, --follow, --tail <n>, --boot (show boot logs).

• container stats: Live stream of resource usage.

- Options: --no-stream.

• container export CONTAINER: Exports container's filesystem to an image/tar archive.
• container prune: Removes all stopped containers.

Image Management

• container build [OPTIONS] PATH: Builds an image from a Dockerfile.

- Options: -t <tag>, -f <dockerfile>, --build-arg <key=val>, --no-cache, -o, --output <type>, --pull (fetch latest image), --dns <dns> (custom DNS).

• container image pull [OPTIONS] NAME[:TAG]: Pulls an image from a registry.

- Options: --platform <os/arch> (e.g., linux/amd64, linux/arm64), --arch <arch>, --os <os>.

• container image push NAME[:TAG]: Pushes an image.
• container image list: Lists local images (aliases: ls, images).
• container image delete [OPTIONS] IMAGE...: Deletes images (aliases: rm, rmi).

- Options: -f, --force (force delete).

• container image prune: Removes unused images.
• container image tag SOURCE TARGET: Tags an image.
• container image inspect IMAGE...: JSON details of images.
• container image save -o <path> IMAGE: Saves image to tar.

- Options: --platform <os/arch>.

• container image load -i <path>: Loads image from tar.

Volume Management

• container volume create [OPTIONS] NAME: Creates a volume.

- Options: -s, --size <size>, --label <key=val>.

• container volume list: Lists volumes (aliases: ls).
• container volume inspect NAME...: JSON details.
• container volume delete NAME...: Deletes volumes (aliases: rm).
• container volume prune: Removes unused volumes.

Network Management

• container network create NAME: Creates a network.

- Options: --subnet <cidr>, --subnet-v6 <cidr>, --label <key=val>.

• container network list: Lists networks (aliases: ls).
• container network inspect NAME...: JSON details.
• container network delete NAME...: Deletes networks (aliases: rm).
• container network prune: Removes unused networks.

Registry & Builder

• container registry login SERVER: Log in to a registry.

- Options: -u <username>, --password-stdin, --scheme <auto|https|http>.

• container registry logout SERVER: Log out.
• container registry list: Lists configured registries.
• container builder status: Check BuildKit builder status.
• container builder start: Start the builder manually.

- Options: --cpus <count>, --memory <size>.

• container builder stop: Stops the builder.
• container builder delete: Deletes the builder.
• container builder prune: Clear builder cache.