# Where Is the Main Entry Point for the apple/container Application?

> Discover the main entry point for the apple/container application located at Sources/CLI/ContainerCLI.swift. Learn how the @main struct bootstraps the container system.

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

---

**The main entry point for the apple/container application is defined in [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift) as a `@main` struct conforming to `AsyncParsableCommand`, which immediately delegates to `Application.main()` to bootstrap the container system.**

The apple/container repository provides a Swift-based container runtime for macOS. Understanding where the main entry point resides is essential for developers contributing to the codebase or extending the CLI functionality. The primary executable is launched through a specific Swift source file that implements the modern `@main` attribute introduced in Swift 5.3.

## Locating the Entry Point in ContainerCLI.swift

The definitive starting point for the `container` binary is located at [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift). This file contains the **ContainerCLI** struct marked with the `@main` attribute, which signals the Swift runtime to use this type as the program's entry point.

According to the apple/container source code, the struct conforms to `AsyncParsableCommand` from the Swift ArgumentParser library. This configuration enables automatic command-line argument parsing and asynchronous execution.

The key implementation from lines 21-33 shows the entry point structure:

```swift
@main
public struct ContainerCLI: AsyncParsableCommand {
    public init() {}

    @Argument(parsing: .captureForPassthrough)
    var arguments: [String] = []

    public static let configuration = Application.configuration

    public static func main() async throws {
        try await Application.main()
    }

    public func run() async throws {
        var application = try Application.parse(arguments)
        try application.validate()
        try application.run()
    }
}

```

When the compiled executable launches, the Swift runtime invokes the `main()` method, which immediately forwards control to `Application.main()`.

## How the Entry Point Bootstraps the Application

The entry point follows a clear delegation pattern. Rather than containing complex logic itself, **ContainerCLI** serves as a thin wrapper that initializes the **Application** type defined in [`Sources/CLI/Application.swift`](https://github.com/apple/container/blob/main/Sources/CLI/Application.swift).

The execution flow proceeds as follows:

1. The `container` binary starts and the Swift runtime identifies the `@main` attribute on **ContainerCLI**
2. `ContainerCLI.main()` invokes `Application.main()` statically
3. The **Application** type parses subcommands, validates configuration, and dispatches to the appropriate handler
4. Higher-level logic including daemon launching and XPC communication resides within the Application layer

This separation of concerns keeps the entry point clean while centralizing command dispatch logic in the Application type.

## Distinguishing the Primary Binary from Plugin Entry Points

Several other modules in the repository contain their own `@main` structs, but these build separate auxiliary binaries rather than the primary `container` executable. These plugin entry points include:

- **`RuntimeLinuxHelper`** in [`Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift`](https://github.com/apple/container/blob/main/Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift) – Standalone helper binary for Linux runtime integration
- **`NetworkVmnetHelper`** – Separate networking helper utility  
- **`MachineAPIServer`** – Standalone API server binary
- **`ImagesHelper`** – Image management utility
- **`APIServer`** – Core API server implementation

These files produce distinct executables defined in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift), whereas [`ContainerCLI.swift`](https://github.com/apple/container/blob/main/ContainerCLI.swift) produces the main `container` command-line tool.

## Practical Usage and Extension Examples

Running the standard container command invokes the entry point immediately:

```bash

# Display help text (triggers ContainerCLI.main())

$ container --help

# Launch an interactive container (arguments passed through to Application)

$ container run -it ubuntu bash

```

Developers can extend the CLI by implementing new `ParsableCommand` conforming types. Register these in [`Sources/CLI/Application.swift`](https://github.com/apple/container/blob/main/Sources/CLI/Application.swift) to make them available as subcommands:

```swift
import ArgumentParser

struct MyCommand: AsyncParsableCommand {
    static var configuration = CommandConfiguration(
        commandName: "mycmd",
        abstract: "A custom container subcommand."
    )

    @Option(name: .shortAndLong, help: "Optional flag")
    var flag: Bool = false

    func run() async throws {
        print("Running MyCommand, flag = \(flag)")
    }
}

```

Compile with `swift build` to integrate the new command into the main binary.

## Summary

- The **main entry point** for apple/container is [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift), containing the `@main` attributed **ContainerCLI** struct
- **ContainerCLI** conforms to `AsyncParsableCommand` and delegates immediately to `Application.main()`
- The **Application** type in [`Sources/CLI/Application.swift`](https://github.com/apple/container/blob/main/Sources/CLI/Application.swift) handles actual command parsing and system bootstrapping
- Several **plugin modules** contain separate `@main` entry points for auxiliary binaries, but these are not the primary container executable
- All execution begins with the Swift runtime locating the `@main` attribute and invoking the static `main()` method

## Frequently Asked Questions

### What file contains the main entry point for the apple/container application?

The main entry point is located in [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift). This Swift file defines the **ContainerCLI** struct marked with the `@main` attribute, which serves as the launching point for the `container` executable when invoked from the command line.

### How does the ContainerCLI entry point bootstrap the container system?

The **ContainerCLI** struct implements `AsyncParsableCommand` and defines a static `main()` method that immediately calls `Application.main()`. This delegates control to the Application type, which parses arguments, validates configuration, and dispatches to the appropriate subcommand handlers.

### Are there other entry points in the apple/container repository besides the main ContainerCLI?

Yes, several plugin modules define their own `@main` structs for standalone auxiliary binaries, including **RuntimeLinuxHelper**, **NetworkVmnetHelper**, **MachineAPIServer**, and **ImagesHelper**. These produce separate executables defined in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift), not the primary `container` binary.

### Can I extend the main entry point to add custom subcommands?

Yes. Create a new type conforming to `AsyncParsableCommand`, implement the `run()` method with your logic, and register it in [`Sources/CLI/Application.swift`](https://github.com/apple/container/blob/main/Sources/CLI/Application.swift). When you build the project with `swift build`, your custom command becomes available as a subcommand of the main `container` binary.