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

The main entry point for the apple/container application is defined in 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. 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:

@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.

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 – 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, whereas ContainerCLI.swift produces the main container command-line tool.

Practical Usage and Extension Examples

Running the standard container command invokes the entry point immediately:

# 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 to make them available as subcommands:

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, containing the @main attributed ContainerCLI struct
• ContainerCLI conforms to AsyncParsableCommand and delegates immediately to Application.main()
• The Application type in 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. 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, 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. When you build the project with swift build, your custom command becomes available as a subcommand of the main container binary.

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