container

Abstract

A tool for creating and running Linux containers using lightweight virtual machines on a Mac. It is written in Swift, and optimized for Apple silicon.

The Problem

Running Linux containers natively on macOS typically requires a Linux VM orchestration layer (Docker Desktop, Lima, colima) that adds overhead and complexity. container solves this by treating each container as a lightweight virtual machine directly on Apple silicon, using macOS 26 virtualization features. It consumes and produces OCI-compatible images, so it interoperates with standard registries.

What This Does

container is a Swift-based CLI and system service for creating, running, and managing Linux containers as lightweight VMs on Apple silicon Macs. The CLI entry point is Sources/CLI/ContainerCLI.swift, with command implementations organized under Sources/ContainerCommands/ (container, image, machine, network, volume, registry, system subcommands). The system service lives in Sources/Services/RuntimeLinux/Server/RuntimeService.swift and handles the actual VM lifecycle.

The project is a fork of apple/container (49k stars upstream). It uses the Containerization Swift package for low-level container, image, and process management, and exposes a gRPC API server (Sources/APIServer/) plus a build pipeline (Sources/ContainerBuild/).

How It Is Wired

Entry point: Sources/CLI/ContainerCLI.swift parses subcommands and dispatches to handlers in Sources/ContainerCommands/. Each command (e.g., ContainerRun.swift, ImagePull.swift) calls into the system service via the gRPC API server (Sources/APIServer/APIServer.swift and APIServer+Start.swift).

Control flow: CLI → gRPC API → RuntimeService.swift (1,231 lines, the largest file) → VM lifecycle. The API server also handles DNS (ContainerDNSHandler.swift, LocalhostDNSHandler.swift). Persistence uses Sources/ContainerPersistence/ (entity store, config loaders, snapshots) and plugins load from Sources/ContainerPlugin/.

Blast radius: RuntimeService.swift is the hub—it owns VM lifecycle, and any change there ripples across the entire runtime. APIServer.swift is the other high-traffic file, routing all CLI requests. The import graph shows no circular dependencies (407 files analyzed), which keeps the module structure clean.

External effects: The service writes VM state and configs to disk via ContainerPersistence/EntityStore.swift, pulls/pushes images over the network via registry commands, and manages local filesystem state for containers and volumes.

Not mapped: The exact gRPC method surface and VM lifecycle state machine are not documented in this analysis; you'll need to read RuntimeService.swift and the .proto/generated files under Sources/ContainerBuild/ to trace those.

How To Use It

Setup: Requires macOS 26 and Apple silicon. Install via the signed package from the GitHub release page, or build from source per BUILDING.md (uses Makefile and Swift Package Manager).

Running it:

container system start
container run --rm hello-world
container image pull nginx:latest

Configuration: No environment variables required. User data and config persist under system-managed paths via ContainerPersistence/. The examples/container-machine-vscode/Dockerfile shows a dev-container setup.

Real-World Use

A developer on Apple silicon wants a local dev environment without Docker Desktop. They pull a Postgres image, run it, and mount a volume:

container image pull postgres:16
container volume create pgdata
container run -d --name pg -v pgdata:/var/lib/postgresql/data -p 5432:5432 postgres:16
container exec -it pg psql -U postgres

Code Health & Issues

Static analysis found 115 findings (17 high, 97 medium, 1 low) across 3 kinds:

High - Deep nesting (58 instances) — worst in Sources/APIServer/APIServer+Start.swift, Sources/ContainerCommands/BuildCommand.swift, Sources/ContainerCommands/Image/ImageSave.swift (max depth 9). Fix with early returns and extraction.
High - Duplicated code blocks (416 repeated 6-line blocks) — in Package.swift, APIServer.swift, ContainerDNSHandler.swift, AuditToken.c. Extract shared helpers.
High - Oversized file — Sources/Services/RuntimeLinux/Server/RuntimeService.swift at 1,231 lines. Split by responsibility.

Repo hygiene: tests present (104 files), CI via GitHub Actions, license present, no committed secrets, no lockfile committed.

Additional findings from the health audit:

Med - Base image not pinned by digest — examples/container-machine-vscode/Dockerfile uses swift:6.3.2-noble. Pin with @sha256: and enable Dependabot.
Med - No non-root USER in the example Dockerfile. Add an unprivileged user.
Low - No timeout-minutes on workflow jobs — .github/workflows/docs-release.yml and one other. A wedged job runs to the 6-hour default.

The Bottom Line

Solid, well-structured fork of Apple's container tool with clean module boundaries and real test coverage. The main maintenance risks are the oversized RuntimeService.swift and widespread code duplication. Use it if you need native Linux containers on Apple silicon and want to avoid Docker Desktop's VM overhead—but expect to refactor if you plan to extend the runtime service.