How to Set Up a Development Environment for apple/container: Complete Guide

To set up a development environment for apple/container, you need an Apple silicon Mac running macOS 15 or later, Xcode 26 with Swift 6.2, and the repository cloned alongside its sibling containerization package; then build using make APP_ROOT=test-data all test integration.

The apple/container repository provides a Swift-based command-line tool that runs OCI-compatible containers as lightweight VM-based sandboxes on Apple silicon Macs. Setting up a local development environment requires specific hardware, toolchain versions, and a particular repository layout to handle the project's dependency on the separate containerization package. This guide covers the complete setup process from cloning to running your first container locally.

Prerequisites

Before building apple/container, verify your system meets the following requirements defined in the repository's README.md and Package.swift:

• Hardware: Apple silicon (M1, M2, or later)
• Operating System: macOS 15 minimum; macOS 26 recommended
• Xcode: Version 26 set as the active developer directory
• Swift: Version 6.2 (declared in Package.swift)
• Tools: make, git, and bash (standard on macOS)

Optional but recommended for advanced development: protobuf, grpc, and swift-protobuf via Homebrew if you plan to regenerate gRPC code.

Clone the Repository and Dependencies

The container project depends on the containerization package (defined as a dependency in Package.swift). To work on both projects simultaneously or ensure compatibility, clone them side-by-side:

git clone https://github.com/apple/container.git
git clone https://github.com/apple/containerization.git

Your directory structure should look like this:

~/projects/
├── container/
└── containerization/

This layout is required because the build scripts in BUILDING.md assume the sibling directory structure when using swift package edit to develop against a local copy of the containerization code.

Configure the Build Environment

Set Xcode 26 as your active developer directory and verify your Swift toolchain:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
swift --version   # Should display Swift 6.2

No additional dependencies are required for a standard build, as the Swift Package Manager handles all Swift package resolution automatically via the Package.swift manifest.

Build and Test the Project

The repository includes a Makefile that wraps the Swift Package Manager and provides standard development workflows. The recommended development build command is:

make APP_ROOT=test-data all test integration

This command:

• Sets APP_ROOT=test-data to isolate the services from real user data
• Builds all binaries into bin/ and libexec/ via the all target
• Runs unit tests via the test target
• Executes integration tests via the integration target

For a release-optimized build, use:

BUILD_CONFIGURATION=release make all

To install the binaries system-wide after building:

sudo make install

Run the Container System Locally

After a successful build, start the container daemon:

bin/container system start

Verify the installation by running a test container:

bin/container run -d --name hello debian:bookworm echo "Hello, world!"

When finished testing, stop the system:

bin/container system stop

Develop Using a Local Copy of Containerization

To modify low-level container primitives in the containerization package while working on container, you must point the main project to your local copy:

1. Edit Package.swift to replace the remote URL with a local path reference
2. Execute the Swift Package Manager edit commands:

/usr/bin/swift package edit --path ../containerization containerization
/usr/bin/swift package update containerization

3. Rebuild with make clean all

When finished, revert to the remote dependency by restoring the original Package.swift line or running swift package unedit containerization.

Debugging and Code Quality Tools

The repository provides tools to maintain code quality and debug running services:

Pre-commit Hooks: Install git hooks that run swift-format and enforce license headers:

make pre-commit

Debug XPC Helpers: To debug the XPC helpers (such as the Linux runtime in Sources/Plugins/RuntimeLinux/), set the environment variable before starting:

export CONTAINER_DEBUG_LAUNCHD_LABEL=com.apple.container.container-runtime-linux.test
bin/container system start

This causes the helper to pause on launch, waiting for a debugger to attach, as documented in BUILDING.md.

Summary

• Hardware Requirements: Apple silicon Mac with macOS 15+ and Xcode 26
• Repository Layout: Clone both container and containerization side-by-side for local development
• Build Command: Use make APP_ROOT=test-data all test integration for development builds
• Key Files: Configuration lives in Package.swift, build logic in Makefile, and detailed instructions in BUILDING.md
• Local Development: Use swift package edit to develop against local changes in the containerization dependency
• Entry Point: The CLI implementation is located in Sources/CLI/ContainerCLI.swift

Frequently Asked Questions

What hardware is required to build apple/container?

You must use an Apple silicon Mac (M1, M2, or later). The project builds and runs only on macOS, specifically version 15 or later, with macOS 26 recommended for full compatibility according to the README.md requirements section.

Why do I need to clone the containerization repository separately?

The container project depends on the containerization package as defined in Package.swift. While the package manager can fetch this automatically from the remote URL, cloning it locally allows you to modify low-level container primitives and test changes using swift package edit. The build scripts assume a side-by-side directory structure when working with local copies.

How do I run the test suite after building?

Execute make APP_ROOT=test-data test for unit tests or make APP_ROOT=test-data integration for the integration test suite. The APP_ROOT=test-data parameter is critical as it forces the services to use an isolated test directory rather than touching real user data on your system.

Can I contribute to the project without installing the Release version?

Yes. After building with make all, you can run the locally compiled binaries directly from the bin/ directory without running sudo make install. Use bin/container system start to test your changes, and refer to Sources/ContainerCommands/ for the implementation of commands like run, build, and system.

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