How to Install and Manage Custom Linux Kernels with Apple Container

You can install custom Linux kernels in Apple Container by using the container system kernel set command for global installation, the -k flag for per-container overrides, or by editing the [kernel] section in config.toml for persistent configuration.

Apple Container runs containers inside lightweight virtual machines that require a Linux kernel with specific virtualization features. While the CLI can automatically download a recommended Kata Containers kernel, you can also supply your own kernel binary or archive to meet specific hardware or workload requirements. The kernel configuration is managed through the KernelConfig type defined in the runtime configuration.

Understanding Kernel Configuration

The kernel handling logic in Apple Container is driven by the KernelConfig type defined in the runtime configuration file (config.toml). This configuration specifies how the runtime discovers and loads kernel binaries for the virtual machines.

The KernelConfig struct contains two critical fields:

• binaryPath – The path inside the downloaded archive that points to the actual kernel binary.
• url – The remote URL of the archive to download when no kernel is present locally.

Default values for these fields are defined in Sources/ContainerPersistence/ContainerSystemConfig.swift within the repository. When you install a custom kernel, you are essentially updating these configuration values to point to your preferred binary.

Installing Custom Kernels

Apple Container provides three distinct methods for controlling kernel installation and selection.

Install from a Local Binary

To install a kernel binary you have compiled locally, use the --binary flag with the container system kernel set command. This is useful when you have built a custom kernel with specific CONFIG_KVM or CONFIG_VIRTIO_* options enabled.

container system kernel set \
  --binary /usr/local/src/linux/arch/arm64/boot/vmlinux \
  --force

The --force flag overwrites any existing kernel with the same name.

Install from an Archive or Remote URL

You can also install kernels packaged in archives (tarballs or zip files) either locally or downloaded from a remote URL. The binaryPath configuration must correctly point to the kernel location within the archive structure.

# Install from a remote Kata Containers release

container system kernel set \
  --tar https://github.com/kata-containers/kata-containers/releases/download/3.28.0/kata-static-3.28.0-arm64.tar.zst \
  --force

# Install from a local archive

container system kernel set \
  --tar /path/to/kernel-archive.tar

Use the Recommended Kata Kernel

To revert to or install the officially supported Kata Containers kernel that Apple Container recommends, use the --recommended flag:

container system kernel set --recommended

This downloads the default kernel archive configured in the system settings.

Managing Kernels for Specific Containers

You can manage kernel selection at either the global system level or for individual container runs.

Per-Container Kernel Overrides

To use a custom kernel for a single container execution without changing the system-wide configuration, use the -k or --kernel flag with the container run command:

container run \
  -k /opt/kernels/vmlinux-custom \
  -it alpine:latest sh

This override applies only to that specific container instance and does not modify the persistent configuration.

Persistent Configuration via config.toml

For environments like CI pipelines where you need consistent kernel settings, edit the config.toml file directly to persist custom kernel paths:

[kernel]
binaryPath = "/opt/kernels/vmlinux-custom"
url = "file:///opt/kernels/custom-kernel.tar.zst"

After modifying the configuration, restart the Apple Container system services to apply the changes:

container system restart

Alternatively, you can stop and start the services separately:

container system stop && container system start

Verifying Kernel Installation

After installing a custom kernel, verify the current configuration using the container system property list command:

container system property list | grep kernel

For detailed JSON output showing both the binaryPath and url values:

container system property list --format json | jq '.kernel'

You should see binaryPath pointing to your installed file and url showing either the original download URL or a file:// scheme for local installations.

Summary

• Apple Container uses the KernelConfig type in config.toml to manage kernel paths and download URLs, with defaults defined in ContainerSystemConfig.swift.
• Install custom kernels globally using container system kernel set with --binary for local files or --tar for archives.
• Override kernels per-container using the -k flag with container run for temporary testing.
• Persist configuration by editing the [kernel] section in config.toml and restarting the system services.
• Verify installation with container system property list to confirm binaryPath and url values.

Frequently Asked Questions

What kernel configuration options are required for Apple Container?

Your custom Linux kernel must include specific virtualization features to support Apple Container's lightweight virtual machines. Required options include CONFIG_KVM for KVM virtualization support and CONFIG_VIRTIO_* options for VirtIO device drivers. Without these enabled, the kernel will not function correctly within the Apple Container runtime.

How do I check which kernel Apple Container is currently using?

Run the command container system property list and filter for kernel entries, or use the JSON output format with jq to inspect the kernel object specifically. This displays the current binaryPath (location of the kernel binary) and url (source of the kernel), allowing you to verify whether the system is using a custom installation or the default recommended kernel.

What is the difference between using --binary and --tar with the kernel set command?

The --binary flag installs a single, uncompressed kernel file (such as a vmlinux binary) directly into the system. The --tar flag accepts either a local archive path or a remote URL, downloads the archive if necessary, and extracts the kernel binary from within it using the path specified in the binaryPath configuration. Use --binary for standalone kernel files and --tar when the kernel is packaged in a compressed archive.

Can I use different kernels for different containers without changing the system default?

Yes. Use the -k or --kernel flag with the container run command to specify a custom kernel path for a single container execution. This per-container override does not modify the global configuration stored in config.toml or affect other running containers, making it ideal for testing specific kernel versions against individual workloads.

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