# Fundamental Operations Provided by apple/container: A Complete Guide to Swift Container Management

> Explore fundamental operations of apple/container. Learn about 14 OCI-compatible Swift APIs for container management like Create Start Stop Delete Inspect List Exec Logs Kill Prune Stats Copy and Export.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: tutorial
- Published: 2026-07-06

---

**TLDR:** `apple/container` implements 14 core container primitives—Create, Start, Run, Stop, Delete, Inspect, List, Exec, Logs, Kill, Prune, Stats, Copy, and Export—as OCI‑compatible Swift APIs and command‑line tools, each defined as individual structs conforming to `AsyncLoggableCommand` in the `Sources/ContainerCommands/Container/` directory.

The `apple/container` repository provides a Docker‑like container runtime built entirely in Swift, designed specifically for macOS Apple Silicon virtualization. Understanding the fundamental operations it exposes is essential for developers integrating container functionality into macOS applications or interacting with the CLI.

## Complete List of Fundamental Operations

The project exposes its functionality through discrete command structs located in `Sources/ContainerCommands/Container/`. Each operation represents a specific container management primitive.

### Lifecycle Management

These operations handle the birth‑to‑death cycle of a container:

- **Create** ([`ContainerCreate.swift`](https://github.com/apple/container/blob/main/ContainerCreate.swift)): Builds a container object from an image and configuration without starting it.
- **Start** ([`ContainerStart.swift`](https://github.com/apple/container/blob/main/ContainerStart.swift)): Launches a previously created container.
- **Run** ([`ContainerRun.swift`](https://github.com/apple/container/blob/main/ContainerRun.swift)): Combines create and start into a single atomic operation, equivalent to `docker run`.
- **Stop** ([`ContainerStop.swift`](https://github.com/apple/container/blob/main/ContainerStop.swift)): Gracefully terminates a running container with an optional timeout parameter.
- **Delete** ([`ContainerDelete.swift`](https://github.com/apple/container/blob/main/ContainerDelete.swift)): Removes a container from the system, with force‑removal support for running containers.

### Monitoring and Inspection

These operations provide visibility into container state and resource usage:

- **Inspect** ([`ContainerInspect.swift`](https://github.com/apple/container/blob/main/ContainerInspect.swift)): Retrieves low‑level metadata including PID, state, mounts, and network configuration.
- **List** ([`ContainerList.swift`](https://github.com/apple/container/blob/main/ContainerList.swift)): Enumerates containers with filtering capabilities by status, name, or label.
- **Stats** ([`ContainerStats.swift`](https://github.com/apple/container/blob/main/ContainerStats.swift)): Queries live resource consumption including CPU, memory, and I/O metrics.
- **Logs** ([`ContainerLogs.swift`](https://github.com/apple/container/blob/main/ContainerLogs.swift)): Streams or fetches stdout/stderr output from a container.

### Runtime Interaction

These operations manipulate running containers:

- **Exec** ([`ContainerExec.swift`](https://github.com/apple/container/blob/main/ContainerExec.swift)): Executes arbitrary commands inside a running container and returns output.
- **Kill** ([`ContainerKill.swift`](https://github.com/apple/container/blob/main/ContainerKill.swift)): Sends signals (defaulting to `SIGKILL`) to the container’s init process.
- **Copy** ([`ContainerCopy.swift`](https://github.com/apple/container/blob/main/ContainerCopy.swift)): Transfers files and folders between the host filesystem and container.
- **Export** ([`ContainerExport.swift`](https://github.com/apple/container/blob/main/ContainerExport.swift)): Archives a container’s filesystem as a tar file.

### Maintenance and Cleanup

- **Prune** ([`ContainerPrune.swift`](https://github.com/apple/container/blob/main/ContainerPrune.swift)): Bulk‑removes stopped containers with optional filtering criteria.

## Architecture of Container Operations

The fundamental operations follow a layered architecture that separates the CLI interface from the underlying runtime.

**ContainerCLI** ([`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift)) parses user arguments and acts as the entry point. It forwards commands to **ContainerClient** ([`Sources/Services/ContainerAPIService/Client/ContainerClient.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/ContainerClient.swift)), which handles client‑side RPC communication. The client interacts with **ContainersService** ([`Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift)) on the daemon side, which ultimately delegates to **RuntimeService** ([`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift)) for virtual‑machine‑based container execution.

This design ensures that the same fundamental operations are available both via command line and as programmable Swift APIs.

## Working with Fundamental Operations in Swift

Each operation is implemented as an `AsyncLoggableCommand` conforming struct that you can instantiate and execute programmatically.

### Running a Container

The `ContainerRun` operation combines creation and startup:

```swift
import ContainerCommands
import ContainerResource

let run = ContainerRun(
    image: "docker.io/library/alpine:latest",
    command: ["/bin/sh", "-c", "echo hello && sleep 5"]
)

try await run.execute()

```

This corresponds to `ContainerRun` in [`Sources/ContainerCommands/Container/ContainerRun.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerRun.swift).

### Listing Containers

Filter containers by state using `ContainerList`:

```swift
import ContainerCommands

let list = ContainerList(filters: ContainerListFilters(state: .running))
let result = try await list.execute()
print(result)               // JSON array of ContainerStatus structs

```

Implementation resides in [`Sources/ContainerCommands/Container/ContainerList.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerList.swift).

### Fetching Container Logs

Retrieve stdout and stderr without streaming:

```swift
import ContainerCommands

let logs = ContainerLogs(containerID: "my‑container", follow: false)
let output = try await logs.execute()
print(output)               // Combined stdout and stderr

```

Defined in [`Sources/ContainerCommands/Container/ContainerLogs.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerLogs.swift).

### Executing Commands Inside Running Containers

Use `ContainerExec` to run arbitrary binaries inside active containers:

```swift
import ContainerCommands

let exec = ContainerExec(
    containerID: "my‑container",
    command: ["ls", "-la", "/"]
)

let result = try await exec.execute()
print(result)               // Command output string

```

See [`Sources/ContainerCommands/Container/ContainerExec.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerExec.swift) for implementation details.

### Pruning Stopped Containers

Bulk cleanup uses the `ContainerPrune` operation:

```swift
import ContainerCommands

let prune = ContainerPrune()
let summary = try await prune.execute()
print("Pruned \(summary.removedCount) containers")

```

This operation is implemented in [`Sources/ContainerCommands/Container/ContainerPrune.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerPrune.swift).

## Summary

The `apple/container` project provides a comprehensive set of OCI‑compatible fundamental operations:

- **Lifecycle control** through Create, Start, Run, Stop, and Delete
- **Observability** via Inspect, List, Stats, and Logs
- **Runtime management** with Exec, Kill, Copy, and Export
- **Maintenance** using Prune for bulk cleanup

These operations are implemented as discrete Swift structs in `Sources/ContainerCommands/Container/`, orchestrated through `ContainerCLI` and `ContainerClient`, and executed via the daemon‑side `ContainersService` and `RuntimeService`.

## Frequently Asked Questions

### What is the difference between Run and Create+Start in apple/container?

**Run** (`ContainerRun`) is a convenience wrapper that executes both creation and startup atomically, equivalent to `docker run`. **Create** (`ContainerCreate`) only instantiates the container configuration and filesystem overlay without launching the process, allowing you to modify settings before calling **Start** (`ContainerStart`). Use separate calls when you need to inspect or adjust the container configuration between creation and execution.

### How does apple/container handle container logs?

The **Logs** operation (`ContainerLogs` in [`Sources/ContainerCommands/Container/ContainerLogs.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerLogs.swift)) retrieves stdout and stderr streams from the container. It supports both one‑time fetching and following mode for real‑time streaming. The operation interfaces with the daemon’s logging infrastructure through the `ContainersService` layer.

### Can I use these fundamental operations without the command-line interface?

Yes. All operations are exposed as Swift structs conforming to `AsyncLoggableCommand` in the `ContainerCommands` module. You can import the package into your Swift application and call `execute()` on any operation directly, bypassing the `ContainerCLI` parser entirely. The `ContainerClient` class provides the underlying RPC mechanism for programmatic access.

### How does the Copy operation manage file permissions between host and container?

**Copy** (`ContainerCopy` in [`Sources/ContainerCommands/Container/ContainerCopy.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerCopy.swift)) handles bidirectional file transfers between the host filesystem and container root filesystem. It preserves Unix permissions and ownership metadata during transmission. The operation uses the runtime’s virtualization layer to ensure secure file system isolation while allowing data exchange between the host and guest environments.