# Main Directories in the Apple Container Repository: Complete Guide

> Explore the main directories in the apple/container repository. Understand the structure of assets, docs, examples, scripts, signing, Sources, Tests, and .github for Apple's Swift package.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-27

---

**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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/install-init.sh) and [`update-container.sh`](https://github.com/apple/container/blob/main/update-container.sh), which automate the setup process and CI/CD tasks.

When you run [`./scripts/install-init.sh`](https://github.com/apple/container/blob/main/./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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.swift) file defines the `Builder` class that coordinates container image construction.

```swift
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`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.swift) to construct container images according to the pipeline defined in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Tests/ContainerPersistenceTests/ConfigurationLoaderTests.swift) file specifically validates that configuration files decode correctly across edge cases.

Run specific test suites using the command:

```bash
swift test --filter ContainerPersistenceTests/MachineConfigTests

```

This executes tests located under `Tests/ContainerPersistenceTests/`, verifying that [`Sources/ContainerPersistence/ConfigurationLoader.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/.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`](https://github.com/apple/container/blob/main/install-init.sh) and updates via [`update-container.sh`](https://github.com/apple/container/blob/main/update-container.sh).
- **Signing** provides macOS entitlements required for runtime security compliance.
- **Tests** include [`ConfigurationLoaderTests.swift`](https://github.com/apple/container/blob/main/ConfigurationLoaderTests.swift) to validate config parsing in [`Sources/ContainerPersistence/ConfigurationLoader.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ConfigurationLoader.swift).
- **.github/workflows** contains [`pr-build.yml`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/PluginLoader.swift) and [`LaunchPlist.swift`](https://github.com/apple/container/blob/main/LaunchPlist.swift). **ContainerPersistence** focuses on configuration management and model decoding, implemented in [`Sources/ContainerPersistence/ConfigurationLoader.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/.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`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ConfigurationLoader.swift) correctly decodes machine configurations across various edge cases.