# How to Configure Guest Kernel and vminit Image in container config.toml > Learn how to configure guest kernel and vminit image in container config.toml. Override defaults with binaryPath, url, and image fields for the Apple container runtime. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-04 --- **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: ```text ~/.config/container/config.toml ``` This path is read by the `ContainerSystemConfig` struct implemented in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift), which provides default values if the table is missing. Changing them in [`config.toml`](https://github.com/apple/container/blob/main/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: ```toml # ~/.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: ```toml # ~/.config/container/config.toml [vminit] image = "vminit:latest" ``` ## Practical Configuration Examples ### Minimal Complete Configuration This example shows both tables configured to override defaults: ```toml # ~/.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: ```toml [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`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) with schema documented in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/config.toml) in `~/.config/container/config.toml`. This path is read by the persistence layer in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.