container/docs/tutorials/container-system-config-tutorial.md

Customize container default configuration values

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

Take a guided tour of setting configurations for container CLI commands and services.

Configuration sources

The container service loads values from these TOML files at startup, with first-match-wins precedence:

1. Your user file at ~/.config/container/config.toml.
2. An optional file shipped with the container package install at <installRoot>/etc/container/config.toml.

Any key absent from both files falls back to a hardcoded default. For the full schema and defaults, see the config.toml reference.

Create a custom user TOML configuration file

The container service reads your file once at startup, so restart the service whenever you want changes to take effect.

Open or create your config file

Your editable config lives at ~/.config/container/config.toml. Create it if it does not exist:

mkdir -p ~/.config/container
touch ~/.config/container/config.toml

Set the values you want to customize

Open the file in the editor of your choice and add only the sections and keys you want to change.

For this tutorial, increase the default CPU and memory limits used for each new container, and set a DNS domain so containers get hostnames under that domain (a container named my-web-server becomes my-web-server.test).

[container]
cpus = 8
memory = "4g"

[dns]
domain = "test"

Each top-level table maps directly to a section of ContainerSystemConfig.

Restart the container service

To make your edits take effect, stop and start the system:

container system stop
container system start

Route macOS DNS queries for the domain to container

The [dns] domain change above only affects the container service and the containers it runs. Complete the setup by telling macOS to route *.test queries there too:

sudo container system dns create test

Enter your administrator password when prompted. See Networking: Set up DNS-based container names for what this step does.

Verify the values are loaded

Use container system property list (alias ls) to print the merged configuration that the container service is using.

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

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

[dns]
domain = "test"

[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"
digest = "sha256:f63d54507d1f18635d94475077e4c2330de4d8e05cedf25f7c38f063b0e66a91"

[network]

[registry]
domain = "docker.io"

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

For machine-readable output, pass --format json:

container system property list --format json