How to Configure Guest Kernel and vminit Image in container config.toml

Edit ~/.config/container/config.toml to add [kernel] and [vminit] tables with binaryPath, url, and image fields to override the default guest kernel and init image used by the Apple container runtime.

The Apple container open-source project reads its runtime configuration from a TOML file that controls low-level VM settings. You can configure the guest kernel binary and the vminit container image by editing this configuration file, which is parsed by ContainerSystemConfig on every startup to determine which kernel archive to fetch and which init image to run.

Configuration File Location and Structure

The container runtime looks for user-specific settings in ~/.config/container/config.toml. If this file does not exist or specific tables are omitted, the system falls back to hard-coded defaults defined in the source code.

Default Config Path

The runtime expects the configuration at:

~/.config/container/config.toml

This path is read by the ContainerSystemConfig struct implemented in Sources/ContainerPersistence/ContainerSystemConfig.swift. When the file is present, the decoder maps each top-level TOML table into corresponding Swift properties that drive the VM lifecycle.

Configuration Schema Reference

The authoritative schema is documented in docs/container-system-config.md. According to the source code, two critical tables control the VM boot process:

• [kernel] – Defines the guest kernel binary path inside a downloaded archive and the URL of that archive.
• [vminit] – Defines the container-VM init image that runs the vminitd process.

Configuring the Guest Kernel

The [kernel] table tells the runtime where to find the actual kernel binary after unpacking an archive. This is essential when you need to upgrade the Kata Containers kernel or use a custom build.

Kernel Configuration Fields

• binaryPath – The path inside the downloaded archive that points to the kernel binary (e.g., opt/kata/share/kata-containers/vmlinux-6.18.15-186).
• url – The HTTPS URL of the archive to fetch when the kernel is not already cached (e.g., a Kata Containers release tarball).

These values are defined in Sources/ContainerPersistence/ContainerSystemConfig.swift, which provides default values if the table is missing. Changing them in config.toml overrides the defaults for every subsequent container run.

Example: Overriding the Kernel

To use a newer Kata Containers release, specify the archive URL and the internal binary path:

# ~/.config/container/config.toml

[kernel]
binaryPath = "opt/kata/share/kata-containers/vmlinux-6.19.0-200"
url = "https://github.com/kata-containers/kata-containers/releases/download/3.29.0/kata-static-3.29.0-arm64.tar.zst"

When the runtime starts a VM, it downloads the archive at url if not present, extracts it, and uses the binary at binaryPath as the guest kernel.

Configuring the vminit Image

The [vminit] table controls which container image provides the vminitd init process. This image runs inside the microVM and initializes the container environment.

vminit Configuration Fields

• image – A container image reference string. This can be the default bundled image (e.g., ghcr.io/apple/containerization/vminit:0.34.0) or a custom development tag (e.g., vminit:latest).

As implemented in apple/container, the runtime pulls the specified image if it is not cached locally, then launches vminitd from it to bootstrap the container VM.

Example: Using a Custom Development Image

For local development when editing the vminit source, point to a locally built image:

# ~/.config/container/config.toml

[vminit]
image = "vminit:latest"

Practical Configuration Examples

Minimal Complete Configuration

This example shows both tables configured to override defaults:

# ~/.config/container/config.toml

[kernel]
binaryPath = "opt/kata/share/kata-containers/vmlinux-6.18.15-186"
url = "https://github.com/kata-containers/kata-containers/releases/download/3.28.0/kata-static-3.28.0-arm64.tar.zst"

[vminit]
image = "ghcr.io/apple/containerization/vminit:0.34.0"

Development Setup with Local vminit

When iterating on the initialization system, use a local image without affecting the remote registry:

[vminit]
image = "localhost/vminit-dev:latest"

The runtime will treat this as the init image for all new VMs until you revert the configuration.

How Configuration Changes Take Effect

The container runtime applies configuration changes immediately upon the next VM creation. Follow this workflow:

1. Edit ~/.config/container/config.toml with the desired [kernel] and [vminit] values.
2. Run any container command that creates or starts a VM (e.g., container run).
3. The runtime loads the file via ContainerSystemConfig, decodes the tables, and substitutes the provided values for the built-in defaults.
4. For kernel changes, the archive at url is fetched if needed, and the binary at binaryPath is extracted.
5. For vminit changes, the specified image is pulled if not cached, and vminitd is started from it.

To revert to default behavior, delete the corresponding table or comment out the lines with #.

Summary

• Configuration file: Edit ~/.config/container/config.toml to customize runtime behavior.
• Guest kernel: Set [kernel] table with binaryPath (path inside archive) and url (download source).
• Init image: Set [vminit] table with image (container reference).
• Implementation: Parsed by ContainerSystemConfig in Sources/ContainerPersistence/ContainerSystemConfig.swift with schema documented in docs/container-system-config.md.
• Application: Changes take effect on the next VM launch; missing values fall back to hard-coded defaults.

Frequently Asked Questions

What is the default location for the container configuration file?

The runtime looks for config.toml in ~/.config/container/config.toml. This path is read by the persistence layer in Sources/ContainerPersistence/ContainerSystemConfig.swift on every startup.

Do I need to restart the container daemon for changes to take effect?

No. The container runtime reads config.toml fresh each time it creates a VM. Simply edit the file and run your next container command; the new kernel and vminit settings are applied automatically.

Can I use a local container image for vminit?

Yes. Set image in the [vminit] table to any valid container reference, including local tags like vminit:latest or localhost/my-init:dev. The runtime will pull or use the local image as specified.

What happens if I only specify one of the kernel fields?

The ContainerSystemConfig decoder requires both binaryPath and url to properly configure a custom kernel. If you omit one field or the entire [kernel] table, the runtime falls back to the hard-coded defaults defined in the Swift source code.

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