How to Configure Apple Container: A Complete Guide to TOML System Settings

Configure Apple Container by creating a ~/.config/container/config.toml file with TOML tables like [container] and [build], then restart the service with container system stop and container system start to apply changes.

Apple Container is an open-source containerization platform that reads system-wide settings from a TOML configuration file at startup. The configuration system maps each top-level table directly onto Swift structs defined in Sources/ContainerPersistence/ContainerSystemConfig.swift, using a first-match-wins precedence chain to merge user overrides with hard-coded defaults. Understanding this configuration pipeline allows you to customize resource limits, DNS settings, and build parameters while maintaining type safety.

Configuration File Location and Precedence

Apple Container searches for config.toml in two locations, stopping at the first file found:

1. User file – ~/.config/container/config.toml
2. Package-install file – <install-root>/etc/container/config.toml

If a key is missing from both files, the system falls back to hard-coded defaults defined in the Swift model classes such as ContainerConfig and BuildConfig. This hierarchy ensures user-specific settings always override system-wide installations without modifying package files.

Core Configuration Sections

Each TOML table maps one-to-one to a Swift class in ContainerSystemConfig.swift. Only specify the keys you wish to override; unspecified values retain their defaults.

Container Resources (ContainerConfig)

The [container] table controls default CPU and memory allocations for new containers. According to the source code in ContainerSystemConfig.swift, the ContainerConfig class supplies these defaults:

final public class ContainerConfig: Codable, Sendable {
    public static let defaultCPUs = 4
    public static let defaultMemory = try! MemorySize("1g")
    // ...
}

To override these defaults, specify integer values for cpus and memory strings like "4g" or "2048mb":

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

Build Settings (BuildConfig)

The [build] table configures the containerization engine used during image builds. The BuildConfig class defines defaults including defaultRosetta, defaultCPUs, defaultMemory, and defaultImage:

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

Network, DNS, and Registry

Additional tables include [network] for subnet CIDRs, [dns] for domain settings, [registry] for default domains (defaulting to "docker.io"), [kernel] for binary paths, and [vminit] for initialization images. The NetworkConfig and DNSConfig classes handle these sections, with most values defaulting to nil unless explicitly configured.

Step-by-Step Configuration Guide

1. Create the User Configuration Directory

Initialize the configuration directory and file:

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

2. Define Your TOML Overrides

Edit ~/.config/container/config.toml with only the sections you need to change. This example increases container resources and sets a custom DNS domain:

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

[dns]
domain = "test"

The keys map directly to Swift struct properties (e.g., container.cpus maps to ContainerConfig.cpus).

3. Restart the Container Service

Configuration is read once at process startup. Apply changes by restarting the daemon:

container system stop
container system start

These commands are defined in the container CLI reference documentation.

4. Verify the Applied Configuration

Dump the merged configuration to confirm your overrides took effect:

container system property list

For machine-readable output suitable for scripting, use JSON format:

container system property list --format json

The output displays the final resolved values including your custom settings alongside inherited defaults.

Advanced Configuration Options

Plugin-Specific Settings

Plugins can expose their own configuration tables under [plugin.<id>]. The main loader decodes these sections into plugin-specific structs defined in Sources/ContainerPlugin/, ensuring isolation between extensions. Consult individual plugin documentation for available keys within each plugin namespace.

Memory Size and CIDR Formats

The TOML parser uses custom types defined in Sources/ContainerPersistence/Measurement+Parse.swift. The MemorySize type accepts strings such as "4g", "512mb", or "1t", while CIDRv4 and CIDRv6 types handle network notation like "192.168.100.0/24". These convert to strongly-typed Swift values during decoding.

Summary

• Apple Container uses a TOML configuration file located at ~/.config/container/config.toml (user) or <install-root>/etc/container/config.toml (system).
• Configuration sections like [container], [build], and [dns] map directly to Swift structs in Sources/ContainerPersistence/ContainerSystemConfig.swift.
• Default values are defined as static constants (e.g., ContainerConfig.defaultCPUs = 4) and are overridden only by explicitly specified keys.
• Changes require a service restart via container system stop and container system start to take effect.
• Verify active configuration using container system property list --format json.

Frequently Asked Questions

What is the default location for the Apple Container configuration file?

The primary location is ~/.config/container/config.toml in the user's home directory. If this file does not exist, the system falls back to <install-root>/etc/container/config.toml installed with the package. Missing keys in either file use hard-coded defaults from the Swift source.

How do I reset Apple Container settings to default values?

Remove or rename your user configuration file at ~/.config/container/config.toml and restart the service. Without a user config file, the system uses package defaults or built-in constants defined in classes like ContainerConfig and BuildConfig.

What format does Apple Container use for memory sizes in the TOML file?

Memory sizes use human-readable strings parsed by the MemorySize type. Valid formats include "512mb", "4g", "1t" (terabytes), or raw byte integers. The parsing logic resides in Sources/ContainerPersistence/Measurement+Parse.swift.

Do I need to restart the service after editing config.toml?

Yes. Apple Container reads the TOML configuration only once at process startup. After modifying config.toml, you must run container system stop followed by container system start to reload the configuration into the running daemon.

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