Main Directories in the Apple Container Repository: Complete Guide

The apple/container repository contains eight top-level directories—assets, docs, examples, scripts, signing, Sources, Tests, and .github—that separate documentation, build automation, source code, and testing into a modular Swift package structure.

The apple/container repository is Apple's open-source container runtime implementation written in Swift. Understanding the main directories in this repository helps developers navigate the codebase, contribute effectively, and leverage the container tooling for macOS development environments.

Top-Level Directory Structure Overview

The repository follows a clean separation of concerns with eight primary directories at the root level. Each directory serves a specific purpose in the container runtime lifecycle, from visual assets and documentation to core Swift implementation and continuous integration.

The Sources directory contains the runtime implementation split into distinct subsystems, while scripts houses automation for installation and updates. Configuration and security concerns live in signing, and the .github directory manages CI/CD pipelines through GitHub Actions workflows.

Documentation and Asset Directories

assets

The assets directory stores graphic resources used by the documentation and user interface components. These include diagrams, icons, and visual aids that support the repository's documentation and README presentation.

docs

The docs directory contains comprehensive user-facing documentation, including tutorials, technical overviews, and command references. This is where developers find guides on running container-based development environments and understanding the runtime architecture. The docs/command-reference.md file specifically documents the build pipeline used by the Builder class in the source code.

Development and Configuration Directories

examples

The examples directory provides sample projects that demonstrate practical usage patterns. These include ready-to-run configurations showing how to set up container-based development environments, such as the VS Code machine example mentioned in the repository documentation.

scripts

The scripts directory contains shell scripts for installing, updating, and uninstalling the container tooling. Key files include install-init.sh and update-container.sh, which automate the setup process and CI/CD tasks.

When you run ./scripts/install-init.sh from the repository root, the script loads entitlements from signing/container-runtime-linux.entitlements, builds the Swift targets in Sources/ContainerPlugin, and registers the plugin's launch plist defined in Sources/ContainerPlugin/LaunchPlist.swift.

signing

The signing directory holds entitlement files required for macOS code signing of the container runtime and networking components. These entitlements ensure the container runtime complies with macOS security requirements for system-level operations.

Source Code and Implementation

Sources

The Sources directory contains the core Swift implementation split into logical subsystems:

ContainerPlugin: Handles plugin management, state management, and discovery. The Sources/ContainerPlugin/PluginLoader.swift file contains the core logic for discovering and loading container plugins.

ContainerPersistence: Manages configuration loading and model decoding. The Sources/ContainerPersistence/ConfigurationLoader.swift file parses container system configuration files used by the runtime, ensuring proper decoding of machine configurations.

ContainerBuild: Orchestrates the image building pipeline. The Sources/ContainerBuild/Builder.swift file defines the Builder class that coordinates container image construction.

import ContainerBuild

let builder = Builder()
builder.buildImage(named: "my-app") { result in
    switch result {
    case .success(let path):
        print("Image built at \(path)")
    case .failure(let error):
        print("Build failed: \(error)")
    }
}

This Swift code imports the ContainerBuild module and uses the Builder class located at Sources/ContainerBuild/Builder.swift to construct container images according to the pipeline defined in docs/command-reference.md.

Testing and Continuous Integration

Tests

The Tests directory contains unit and integration test suites covering the persistence layer, build pipeline, and CLI progress UI. The Tests/ContainerPersistenceTests/ConfigurationLoaderTests.swift file specifically validates that configuration files decode correctly across edge cases.

Run specific test suites using the command:

swift test --filter ContainerPersistenceTests/MachineConfigTests

This executes tests located under Tests/ContainerPersistenceTests/, verifying that Sources/ContainerPersistence/ConfigurationLoader.swift correctly handles machine configuration parsing.

.github

The .github directory hosts GitHub workflow definitions, issue templates, and automation configuration. The .github/workflows/pr-build.yml file defines the CI pipeline that runs linting, unit tests, and builds on every pull request, ensuring code quality and preventing regressions.

Key Files and Entry Points

Several critical files sit at the root level or within the main directories:

Package.swift: Declares the Swift package structure, products, and dependencies. This is the entry point for Swift Package Manager operations.

README.md: The primary guide for contributors and users, providing overview documentation and quick-start instructions.

Sources/ContainerPlugin/LaunchPlist.swift: Defines the launch property list configuration used when registering the container plugin during installation.

scripts/update-container.sh: Automates updates to the latest container runtime build, complementing the initial installation script.

Summary

• The apple/container repository organizes code into eight main directories: assets, docs, examples, scripts, signing, Sources, Tests, and .github.
• Sources contains three subsystems: ContainerPlugin (plugin handling), ContainerPersistence (configuration), and ContainerBuild (image building).
• Scripts automate installation via install-init.sh and updates via update-container.sh.
• Signing provides macOS entitlements required for runtime security compliance.
• Tests include ConfigurationLoaderTests.swift to validate config parsing in Sources/ContainerPersistence/ConfigurationLoader.swift.
• .github/workflows contains pr-build.yml for continuous integration.

Frequently Asked Questions

What is the purpose of the signing directory in apple/container?

The signing directory contains entitlement files required for macOS code signing of the container runtime and networking components. These entitlements ensure the container runtime meets macOS security requirements, with files like container-runtime-linux.entitlements being referenced during the build process by scripts such as install-init.sh.

How does the ContainerPlugin subsystem differ from ContainerPersistence?

ContainerPlugin handles plugin discovery, loading, and state management through files like Sources/ContainerPlugin/PluginLoader.swift and LaunchPlist.swift. ContainerPersistence focuses on configuration management and model decoding, implemented in Sources/ContainerPersistence/ConfigurationLoader.swift, ensuring container system configurations parse correctly from disk.

Where are the CI/CD workflows defined in the repository?

Continuous integration workflows reside in the .github/workflows directory, specifically in .github/workflows/pr-build.yml. This workflow triggers on every pull request to run linting, execute unit tests via swift test, and validate builds, ensuring changes to Sources/ or Tests/ meet quality standards before merging.

How do I run the test suite locally?

Execute the Swift test target with specific filters to run relevant suites. For example, swift test --filter ContainerPersistenceTests/MachineConfigTests runs the configuration loading tests located in Tests/ContainerPersistenceTests/, validating that Sources/ContainerPersistence/ConfigurationLoader.swift correctly decodes machine configurations across various edge cases.

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