Core Container Management Commands in Apple Container: A Complete Guide

Apple Container provides fourteen core CLI sub-commands—including run, build, exec, and inspect—that manage the full container lifecycle from creation to cleanup on macOS.

The apple/container repository delivers a native container runtime for macOS with a command-line interface that mirrors familiar Docker semantics while leveraging Apple-specific optimizations. Understanding these core container management commands is essential for developers orchestrating workloads on Apple silicon or Intel-based Macs, as they interface directly with the container-runtime-linux daemon and the persistence layers defined in the source.

Lifecycle Overview

Apple Container organizes its CLI around four functional areas: creation and execution, operational control, inspection and monitoring, and system maintenance. These commands are documented in docs/command-reference.md and implemented through the runtime client layer in Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift.

Creation and Execution Commands

container run

The container run command creates and starts a container from an image in a single operation. By default, it executes in the foreground, attaching stdout and stderr to the terminal; use the -d flag to detach it as a background process.

container run -it ubuntu:latest /bin/bash

This command is the primary entry point for most container workflows, combining the logic of create and start while accepting environment variables, volume mounts, and resource constraints.

container build

Use container build to construct OCI-compliant images from a Dockerfile or Containerfile. It supports multi-architecture builds, build arguments, and resource limits during compilation.

container build -t myapp:latest .

container create

The container create command instantiates a container filesystem and configuration without starting the process. This allows for pre-configuration of environment variables, volumes, and network settings before execution.

container create -e MY_VAR=foo -v myvol:/data myapp:latest

The configuration data is persisted through the models defined in Sources/ContainerPersistence/MachineConfig.swift, which handles resource allocations and mount specifications.

Operational Control Commands

container start

Start a previously created (stopped) container with container start. The -a flag attaches to the container's output, while -i keeps stdin open for interactive sessions.

container start $(container list -q -f name=myapp)

container stop and kill

container stop initiates a graceful shutdown by sending SIGTERM, followed by SIGKILL after a configurable timeout. container kill bypasses the grace period entirely, sending a signal (default KILL) immediately to terminate the process.

# Graceful shutdown

container stop myapp

# Immediate termination

container kill myapp

container delete

Remove stopped containers using container delete (aliased as rm). The --force flag enables deletion of running containers by first sending a kill signal.

container delete --force myapp

Inspection and Monitoring Commands

container list

List containers with container list (aliased as ls). By default, it shows only running containers; -a displays all states, and -q outputs only IDs for script automation.

container list -a -q

container exec

Execute a new process inside a running container using container exec. This inherits most flags from run, including environment variables, user context, and TTY allocation.

container exec -it myapp /usr/bin/env

container logs

Retrieve stdout, stderr, or boot logs with container logs. The -f flag follows the log output in real-time, similar to tail -f.

container logs -f myapp

container inspect

Output detailed JSON metadata for one or more containers using container inspect. This includes network settings, mount points, and runtime configuration as stored in the persistence layer.

container inspect myapp | jq .

container stats

Monitor real-time resource utilization—CPU, memory, network, and block I/O—with container stats. Use --no-stream to capture a single snapshot instead of continuous updates.

container stats

Maintenance and Utility Commands

container prune

Reclaim disk space by deleting all stopped containers with container prune. This is a destructive operation that removes containers not currently in the running state.

container prune

container copy

Transfer files between the host and a running container using container copy (aliased as cp). Note that the container must be running for this operation to succeed.

container cp ./local-file.txt myapp:/app/data/

Implementation Architecture

The command-line interface is built through several key Swift modules:

• docs/command-reference.md: Central documentation defining all sub-command signatures and flags.
• Sources/ContainerPersistence/MachineConfig.swift: Defines the data model for container configuration, including resources, environment variables, and volume mounts consumed by CLI parsers.
• Sources/ContainerPlugin/PluginLoader.swift: Loads extensions that modify container functionality, such as custom runtimes or network drivers.
• Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift: Implements the communication layer between the CLI binaries and the container-runtime daemon.
• Package.swift: The Swift package manifest that builds the container binary and its dependent modules.

Practical Examples

Run a one-off container with an interactive shell:

container run -it ubuntu:latest /bin/bash

Build a local image and tag it:

container build -t myapp:latest .

Create, then start a container with pre-configuration:

container create -e MY_VAR=foo -v myvol:/data myapp:latest
container start $(container list -q -f name=myapp)

Execute a command inside a running container:

container exec -it myapp /usr/bin/env

Fetch logs and follow live output:

container logs -f myapp

Show live resource statistics for all containers:

container stats

Summary

• Apple Container provides fourteen core CLI commands covering the full container lifecycle from build and create through stop and delete.
• Creation commands (run, build, create) leverage configuration models in Sources/ContainerPersistence/MachineConfig.swift to define container state.
• Operational commands (start, stop, kill, delete) manage container execution, with stop offering graceful shutdown and kill providing immediate termination.
• Inspection commands (list, exec, logs, inspect, stats) interface with the runtime daemon via Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift to expose container metadata and resource usage.
• Maintenance commands (prune, copy) handle system cleanup and file transfer operations.

Frequently Asked Questions

How does container run differ from container create?

container run combines creation and execution, immediately starting the container process and optionally attaching to it, while container create only prepares the container filesystem and configuration without starting the process. Use create when you need to configure a container before launch, then invoke start separately.

What is the difference between container stop and container kill?

container stop performs a graceful shutdown by sending SIGTERM and waiting for a timeout before sending SIGKILL, allowing processes to clean up. container kill sends the specified signal (default KILL) immediately, forcefully terminating the container without cleanup.

Where are the CLI command definitions documented in the source repository?

The authoritative command reference is documented in docs/command-reference.md, which defines all sub-commands, flags, and options. The underlying implementation parses these arguments through Swift source files and communicates with the runtime via Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift.

Can I delete a running container without stopping it first?

Yes, use container delete --force (or container rm -f), which automatically sends a kill signal to running containers before removing them from the system. Without the --force flag, the command only removes stopped containers.

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