# How to Configure System Properties for Container

> Learn how to configure system properties for your container using the config.toml file and container system property CLI commands. Streamline your container setup and management.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-25

---

**Container system properties are defined through a TOML-based [`config.toml`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/config.toml)** (typically located at `$HOME/.config/container/config.toml`). The file uses standard TOML syntax with top-level tables matching the struct names:

```toml
[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:

```bash

# 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:

```bash

# 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`](https://github.com/apple/container/blob/main/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:

```bash
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`](https://github.com/apple/container/blob/main/config.toml).

## Summary

- Configuration is modeled in **[`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift)** as a hierarchy of `Codable` structs.
- Persistent settings live in **[`config.toml`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.