How to Configure Default Resource Limits in Apple Container's config.toml

Edit the [container] table in Sources/Plugins/RuntimeLinux/config.toml to set system-wide CPU, memory, and ulimit values that apply automatically to every container instance.

Apple Container uses a TOML-based configuration system to define baseline resource constraints for the Linux runtime. By modifying the plugin-specific configuration file, you establish default boundaries that prevent individual containers from consuming excessive host resources unless explicitly overridden at launch time.

Locating the Runtime Configuration File

The default resource limits are controlled by the RuntimeLinux plugin configuration. This file resides at a fixed path within the repository structure:

Sources/Plugins/RuntimeLinux/config.toml

This TOML file contains the runtime abstraction metadata and service configuration, including the optional [container] table where you define global limits. The runtime reads these values during initialization and applies them as baseline constraints before merging with any command-line arguments.

Available Resource Limit Options

Inside the [container] table, Apple Container recognizes four specific keys for resource management:

Key	Type	Description
cpu	Integer	Number of virtual CPU cores allocated to each container
memory	String	Maximum RAM with size suffix (e.g., "2GiB" or "512MiB")
swap	String	Optional swap space limit using the same suffix format
ulimit	Array	POSIX resource limits formatted as "type=soft:hard" strings

According to the Apple Container source code, the ulimit array accepts standard Linux limit types such as nofile, nproc, and stack, specified as "nofile=1024:2048" where the first value is the soft limit and the second is the hard limit.

Configuring Default Limits in config.toml

To establish system-wide resource boundaries, add or modify the [container] section in Sources/Plugins/RuntimeLinux/config.toml:

# Sources/Plugins/RuntimeLinux/config.toml

abstract = "Linux container runtime plugin"
author   = "Apple"
version  = 0.1

[servicesConfig]
loadAtBoot   = false
runAtLoad    = false
defaultArguments = []

[container]
cpu    = 2
memory = "4GiB"
ulimit = ["nofile=1024:2048"]
swap   = "1GiB"

In this configuration, every container launched by the runtime inherits 2 virtual CPUs, 4 GiB of RAM, 1 GiB of swap, and a maximum of 1024 open files (soft limit) or 2048 (hard limit). These defaults persist until you explicitly modify the file or override them via CLI flags.

Overriding Defaults Per Container

While the config.toml settings provide global defaults, you can override specific limits for individual containers using the --ulimit command-line flag. The runtime merges CLI arguments with the configuration file values, with command-line options taking precedence.

For example, to temporarily increase the open file limit for a specific workload:

container run --ulimit nofile=2048:4096 my-image

This container receives the overridden file descriptor limit while retaining the default CPU and memory settings from config.toml.

Reloading Configuration Changes

After editing Sources/Plugins/RuntimeLinux/config.toml, you must restart the container system for changes to take effect. The runtime reads the configuration file only during initialization, not dynamically.

Execute the following commands to apply new default resource limits:

container system stop
container system start

Once restarted, all subsequently launched containers inherit the updated limits defined in the [container] table.

Summary

• Primary configuration file: Sources/Plugins/RuntimeLinux/config.toml contains the [container] table for default resource limits in Apple Container.
• Supported limits: Configure cpu, memory, swap, and ulimit arrays to constrain container resources automatically.
• Value formats: Use integers for CPU counts, quoted strings with size suffixes (GiB/MiB) for memory, and "type=soft:hard" strings for ulimit entries.
• Override capability: Command-line --ulimit flags merge with and override config.toml defaults for specific container instances.
• Activation requirement: Restart the container system (container system stop && container system start) after modifying the TOML file to load new defaults.

Frequently Asked Questions

Where is the Apple Container config.toml file located for default resource limits?

The default resource limits are defined in Sources/Plugins/RuntimeLinux/config.toml within the RuntimeLinux plugin source tree. This path is hardcoded in the plugin architecture and represents the canonical location for Linux runtime configuration.

What units does Apple Container accept for memory and swap limits?

Apple Container accepts string values with binary size suffixes such as GiB (gibibytes) and MiB (mebibytes). For example, specify "4GiB" for 4 gibibytes or "512MiB" for 512 mebibytes. These strings must be quoted in the TOML file to ensure proper parsing.

Do I need to restart Apple Container after editing config.toml?

Yes. Apple Container reads the config.toml file only during system initialization. After modifying default resource limits, execute container system stop followed by container system start to reload the configuration and apply new defaults to future container launches.

Can I set different default ulimits for different resource types?

Yes. The ulimit key accepts an array of strings, allowing you to specify multiple POSIX resource limits simultaneously. Format each entry as "type=soft:hard", such as ["nofile=1024:2048", "nproc=1024:2048", "stack=8388608:16777216"] to configure file descriptors, processes, and stack size limits concurrently.

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