How to Configure System Properties for Container

Container system properties are defined through a TOML-based config.toml file decoded into the ContainerSystemConfig Swift model, with runtime overrides managed via the container system property CLI commands.

The apple/container repository implements a hierarchical configuration system that serves as the single source of truth for container runtime behavior. When you configure system properties for container operations, the service reads config.toml, merges it with any CLI-provided overrides, and stores the resulting ContainerSystemConfig in memory during startup.

Configuration Model Architecture

The ContainerSystemConfig Swift Model

The configuration schema is defined in Sources/ContainerPersistence/ContainerSystemConfig.swift. This file contains the root ContainerSystemConfig struct, which mirrors the TOML file structure through nested Codable types:

• BuildConfig – Builder VM resources (CPU, memory, image, Rosetta)
• ContainerConfig – Per-container defaults when flags like --cpus are omitted
• DNSConfig – Optional domain suffix for container hostnames
• KernelConfig – Kernel archive path and URL settings
• NetworkConfig – Default IPv4/IPv6 subnets for auto-created networks
• RegistryConfig – Implicit Docker registry domain
• VminitConfig – Image for the lightweight VM boot-loader (vminitd)

Default Value Resolution

Each struct implements init(from:) with hard-coded defaults defined in fields like BuildConfig.defaultCPUs or KernelConfig.defaultBinaryPath. Missing sections in config.toml automatically fall back to these values, ensuring the system always operates with valid parameters.

Methods to Configure System Properties

Edit the config.toml File

For persistent, machine-wide defaults, create or edit config.toml (typically located at $HOME/.config/container/config.toml). The file uses standard TOML syntax with top-level tables matching the struct names:

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

[network]
subnet = "192.168.200.0/24"

Use CLI Property Commands

Apply temporary or persisted changes without editing files directly:

# Set a runtime-only property (lost after restart)

container system property set build.cpus 6

# Persist to config.toml

container system property set --persist network.subnet "10.0.0.0/24"

# Reset to built-in default

container system property reset build.memory

Runtime Overrides

When starting the system, you can pass ephemeral overrides that exist only for that session. These are merged with the file-based configuration during container system start.

Inspecting Current Configuration

Verify effective settings using the list (or ls) subcommand, which outputs the merged configuration:

# Default TOML format

container system property list

# JSON for scripting

container system property list --format json

# Human-readable table

container system property list --format table

Configuration Sections Reference

Each top-level table in config.toml corresponds to a specific subsystem:

Section	Default Source	Purpose
build	BuildConfig.default* fields	Builder VM resource allocation
container	ContainerConfig.default*	Default resource limits for new containers
dns	DNSConfig (optional)	Domain suffix configuration
kernel	KernelConfig.defaultBinaryPath	Kernel archive internal path and URL
network	NetworkConfig (optional)	Automatic network subnet definitions
registry	RegistryConfig.defaultDomain	Default Docker registry when none specified
vminit	VminitConfig.defaultImage	VM boot-loader image reference

Applying Configuration Changes

Most changes require a system restart to take effect. Reload the configuration by stopping and starting the service:

container system stop
container system start

For changes made via container system property set without --persist, the values apply immediately to the running system but are lost on restart unless written to config.toml.

Summary

• Configuration is modeled in Sources/ContainerPersistence/ContainerSystemConfig.swift as a hierarchy of Codable structs.
• Persistent settings live in config.toml, while runtime overrides use container system property set.
• Missing values fall back to hard-coded defaults defined in each struct's init(from:) implementation.
• The CLI supports TOML, JSON, and table output formats for inspection.
• Restart the system with container system stop and container system start to reload file-based configuration.

Frequently Asked Questions

Where is the default config.toml file located?

The default location is $HOME/.config/container/config.toml. When you use container system property set --persist, the CLI writes to this path automatically.

Do I need to restart after changing system properties?

Yes. File-based changes to config.toml require a restart using container system stop followed by container system start. Runtime changes via container system property set (without --persist) take effect immediately but are lost on restart.

What output formats are supported for property inspection?

The container system property list command supports TOML (default), JSON, and table formats via the --format flag. JSON is particularly useful for scripting and automation.

How do I reset a property to its default value?

Use the reset subcommand followed by the property key. For example, container system property reset build.cpus restores the CPU count to the value defined in BuildConfig.defaultCPUs within the source code.

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