Command-Line Interface for Managing Containers with Apple Container

Yes, the container CLI provides a native Swift-based command-line interface for managing containers, enabling system control, image operations, and full lifecycle management of OCI-compatible Linux containers on macOS Apple Silicon.

The apple/container repository delivers a complete command-line interface for managing containers directly from the terminal. This native Swift tool serves as the primary user entry point, translating sub-commands into calls to the underlying Containerization framework that drives the Apple Virtualization hypervisor and the vmnet networking stack.

CLI Architecture and Implementation

The command-line interface is architected as a thin façade over the runtime's Swift APIs. According to Package.swift, the CLI depends on Swift's ArgumentParser library to handle sub-command parsing, flag validation, and dispatch logic.

The architecture follows a layered approach:

• CLI front-end (Package.swift): Parses sub-commands and dispatches to runtime APIs.
• Containerization package: Provides Swift APIs for image manipulation and container creation.
• Virtualization back-end: Leverages Apple's Virtualization framework via the container Swift package.
• Networking layer (Sources/SocketForwarder): Manages vmnet interfaces, port forwarding, and DNS services.
• Persistence layer (Sources/ContainerPersistence): Stores container state, volumes, and configuration on disk.

Long-running operations display progress bars implemented in Sources/TerminalProgress, which coordinates real-time terminal feedback while the runtime processes filesystem and network I/O.

System Control Commands

Before running containers, you must start the background service that hosts all containers using the system sub-command:

# Start the container service

container system start

# Stop the background service

container system stop

Image Management Operations

The CLI provides first-class support for OCI registry operations, allowing you to pull, build, and push images.

To pull an image from any OCI-compliant registry:

container image pull docker.io/library/ubuntu:latest

Building images from Dockerfiles uses the build sub-command:

container build -t myapp:1.0 .

Push operations distribute images to remote registries:

container image push myregistry.example.com/myapp:1.0

Container Lifecycle Management

Create and run containers using the run command, which supports port mapping, volume mounts, and resource limits:

# Create and start an interactive container with port forwarding

container run --name my-ubuntu \
    --publish 8080:80 \
    --volume ~/mydata:/data \
    docker.io/library/ubuntu:latest \
    /bin/bash

Monitor active containers with the ps shortcut:

container ps  # Equivalent to `container container list --running`

Stop and remove containers using dedicated sub-commands:

container stop my-ubuntu
container rm my-ubuntu

Resource Configuration Options

The CLI exposes flags for resource configuration, including CPU and memory limits, port exposure via --publish, and volume mounting via --volume. These options map directly to the underlying Containerization API that configures the Apple Virtualization framework parameters.

Summary

• The container CLI is a native Swift application built on the ArgumentParser library, declared in Package.swift.
• It provides sub-commands for system control (system start/stop), image management (image pull/push/build), and container lifecycle (run, ps, stop, rm).
• The interface acts as a thin façade over the Containerization Swift package, which manages virtualization via Apple Virtualization and networking via Sources/SocketForwarder.
• State persistence is handled by Sources/ContainerPersistence, while progress reporting is implemented in Sources/TerminalProgress.
• All command syntax is documented in docs/command-reference.md, while architectural details appear in docs/technical-overview.md.

Frequently Asked Questions

How do I start the container service before running containers?

You must start the background system service using container system start before executing any container operations. This initializes the virtualization environment and networking stack required to host Linux containers on macOS.

Where is the full command reference documented?

The complete list of sub-commands, flags, and usage patterns resides in the repository's docs/command-reference.md file. This document provides authoritative syntax for all CLI operations including advanced resource configuration options.

What programming language is the CLI built with?

The CLI is written in Swift and uses Apple's ArgumentParser library for command-line parsing, as specified in the Package.swift manifest. It interfaces with the underlying runtime through the Containerization Swift package, which implements the virtualization and filesystem layers.

Does the CLI support building images from Dockerfiles?

Yes, the container build command supports building OCI-compatible images from Dockerfiles. The CLI processes the build context locally and stores the resulting image in the local container store, ready for execution or pushing to remote registries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}