container/docs/container-system-config.md

config.toml reference

Important

This file contains documentation for the CURRENT BRANCH. To find documentation for official releases, find the target release on the Release Page and click the tag corresponding to your release version.

Example: release 0.4.1 tag

For a guided walk-through on setting default values, see Container system config tutorial.

Source of truth: Sources/ContainerPersistence/ContainerSystemConfig.swift.

Viewing your configuration

Use container system property list (alias ls) to print the merged configuration the container service is actually using — combining your config.toml with hardcoded defaults for anything you haven't set:

% container system property list
[build]
cpus = 2
memory = "2048mb"
rosetta = true
image = "ghcr.io/apple/container-builder-shim/builder:0.13.1"

[container]
cpus = 4
memory = "1gb"

[dns]
domain = "test"

[kernel]
binaryPath = "opt/kata/share/kata-containers/vmlinux-6.18.35-197-debug"
url = "https://github.com/kata-containers/kata-containers/releases/download/3.32.0/kata-static-3.32.0-arm64.tar.zst"
digest = "sha256:8736c054d9223974735394f822000823baef509e1c33405ec798240fa9b6e4b5"

[network]

[registry]
domain = "docker.io"

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

Pass --format json for machine-readable output.

Top-level schema

[build]      # builder VM resources and image
[container]  # default per-container resources
[dns]        # default DNS domain for DNS resolution on host
[kernel]     # guest kernel binary path, download URL, and digest
[network]    # default subnets for new networks
[registry]   # default registry domain
[vminit]     # default vminitd image to use
[plugin.<id>]  # zero or more plugin-scoped sections

All top-level sections are optional. Omitted sections fall back to their defaults wholesale.

[build]

Resources and image used for the builder VM that runs container build.

Key	Type	Default	Description
rosetta	Bool	true	Whether the builder VM uses Rosetta translation for non-native architectures.
cpus	Int	2	CPU count for the builder VM.
memory	MemorySize	"2048mb"	RAM allocation for the builder VM.
image	String	ghcr.io/apple/container-builder-shim/builder:<tag>	Reference for the builder image. The tag segment is taken from the project's bundled container-builder-shim version.

To prevent the use of Rosetta translation during container builds on a Mac with Apple silicon, set rosetta = false:

[build]
rosetta = false

This ensures builds only produce native arm64 images, with no x86_64 emulation.

[container]

Defaults applied when container run / container create is invoked without --cpus or --memory.

Key	Type	Default	Description
cpus	Int	4	Default CPU count per container.
memory	MemorySize	"1g"	Default RAM per container.

[dns]

Key	Type	Default	Description
domain	String?	unset	Local DNS domain appended to container hostnames (e.g. "test" makes my-web-server resolvable as my-web-server.test). When unset, no domain is appended. See Networking: Set up DNS-based container names for the full walkthrough.

[kernel]

Guest kernel used when launching container VMs. Defaults change per release as kernels are bumped — check the source for current values.

Key	Type	Default	Description
binaryPath	String	"opt/kata/share/kata-containers/vmlinux-6.18.35-197-debug"	Path inside the downloaded kernel archive that points to the kernel binary.
url	URL	"https://github.com/kata-containers/kata-containers/releases/download/3.32.0/kata-static-3.32.0-arm64.tar.zst"	Archive to download when no kernel is installed. Encoded and decoded as a plain string in TOML.
digest	String	"sha256:8736c054d9223974735394f822000823baef509e1c33405ec798240fa9b6e4b5"	Expected digest for the archive, for example sha256:<hex>. Required when configuring a custom url.

[network]

Default subnets used when creating networks without explicit --subnet / --subnet-v6 flags.

Key	Type	Default	Description
subnet	CIDRv4?	unset	IPv4 CIDR (e.g. "192.168.100.0/24"). When unset, the system auto-allocates a non-overlapping subnet.
subnetv6	CIDRv6?	unset	IPv6 CIDR (e.g. "fd00:abcd::/64"). When unset, the system auto-allocates.

[registry]

Key	Type	Default	Description
domain	String	"docker.io"	Registry assumed when an image reference omits the registry host (e.g. alpine → docker.io/library/alpine).

[vminit]

Key	Type	Default	Description
image	String	ghcr.io/apple/containerization/vminit:<tag>	Reference for the vminitd image used to boot container VMs. The tag segment is taken from the project's bundled containerization version.

[plugin.<id>]

Plugins can ship their own configuration schemas under [plugin.<id>], where <id> is the plugin's identifier. Each plugin defines and reads its own section — values under one plugin's section cannot leak into another's. Consult the documentation for the specific plugin you want to configure.

Key	Type	Notes
<plugin-defined>	varies	Schema is defined by the plugin. TODO: Add tutorial on setting plugin specific values.

Type formats

MemorySize format

Quoted string with a numeric prefix and a binary unit suffix. Parsing is case-insensitive; the suffix may be one of:

Suffix family	Unit	Example values
b	bytes	"1024b"
k, kb, kib	kibibytes (1024 bytes)	"512k", "512kb"
m, mb, mib	mebibytes (1024 KiB)	"2048mb"
g, gb, gib	gibibytes (1024 MiB)	"4g", "4gb"
t, tb, tib	tebibytes	"1t"
p, pb, pib	pebibytes	"1p"

All units are binary (powers of 1024), even when written with kb/mb/gb. The encoded form uses lowercase suffix b/kb/mb/gb/tb/pb, e.g. a value parsed from "2g" is emitted as "2gb".

A bare integer (e.g. "2048") parses as bytes.

Source: Sources/ContainerPersistence/Measurement+Parse.swift.

CIDRv4 / CIDRv6

Quoted string. IPv4 example: "192.168.100.0/24". IPv6 example: "fd00:abcd::/64". The loader rejects invalid CIDR strings at decode time.