How to Configure CPU, Memory, and Disk Resources in Apple Container

Resource limits in Apple Container are configured through the config.toml file for persistent defaults and CLI flags for per-container overrides, while disk space is managed via system-wide housekeeping commands.

Apple Container runs each workload inside a lightweight virtual machine, requiring explicit configuration of compute resources to ensure optimal performance. Understanding how to configure container resources prevents resource contention on macOS hosts and ensures workloads receive adequate CPU and memory. This guide covers the configuration file schema, command-line overrides, and disk management strategies based on the apple/container source code.

Setting Persistent Defaults in config.toml

Apple Container stores persistent defaults in the [container] section of config.toml. These values apply to every container unless explicitly overridden.

The Configuration File Location

The user-specific configuration file resides at ~/.config/container/config.toml. When you execute container run or container create without explicit resource flags, the system reads these defaults.

CPU and Memory Syntax

Set default vCPUs using the cpus key (integer) and RAM using the memory key (quoted string). According to the schema in docs/container-system-config.md, the default configuration allocates 4 CPUs and 1 GB of memory:

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

MemorySize Format

The memory field accepts binary units: b (bytes), k (kibibytes), m (mebibytes), g (gibibytes), t (tebibytes), and p (pebibytes). The parser is case-insensitive and implemented in Sources/TerminalProgress/Measurement+Parse.swift.

Example configuration:

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

Overriding Resources with CLI Flags

For per-command overrides, use the --cpus and --memory flags with container run, container create, or container builder start. These flags allocate specific resources to the backing VM for that container instance.

Flag Syntax

Both flags accept the same binary units as the configuration file. For example:

container run --rm --cpus 8 --memory 32g myimage

If omitted, the command inherits values from config.toml. As documented in docs/how-to.md, CLI flags take precedence over file-based defaults.

Managing Disk Usage

Unlike CPU and memory, Apple Container does not enforce per-container disk quotas. Instead, disk usage accumulates across images, containers, and volumes on the host filesystem.

Inspecting Disk Consumption

Use container system df to view total, used, and reclaimable space across all resources. This command reports storage statistics as referenced in docs/command-reference.md.

Reclaiming Space

Run container system prune to remove stopped containers, dangling images, and unused volumes. For a more aggressive cleanup that removes all unused images, add the -a flag.

# View current usage

container system df

# Remove unused resources

container system prune -a

Summary

• Configure persistent CPU and memory defaults in ~/.config/container/config.toml under the [container] section.
• Override defaults per container using --cpus and --memory flags with binary units (k, m, g, t).
• Disk space is managed system-wide via container system df and container system prune; no per-container limits exist.
• Memory values are parsed by the helper in Sources/TerminalProgress/Measurement+Parse.swift using standard binary prefixes.

Frequently Asked Questions

Where is the Apple Container configuration file located?

The configuration file is located at ~/.config/container/config.toml. This user-specific file stores default resource allocations that apply to every container unless overridden by CLI flags.

Can I set disk quotas per container in Apple Container?

No, Apple Container does not support per-container disk quotas. Containers, images, and volumes share the host filesystem. You manage disk usage globally using container system df to inspect usage and container system prune to reclaim space from stopped containers and unused images.

What units are supported for memory allocation?

Apple Container supports binary size units: b (bytes), k (kibibytes), m (mebibytes), g (gibibytes), t (tebibytes), and p (pebibytes). These are case-insensitive and parsed by the Measurement+Parse.swift utility in the source code.

Do CLI flags override config.toml settings?

Yes. When you specify --cpus or --memory on the command line with container run, container create, or container builder start, these values take precedence over the defaults defined in config.toml. If no flags are provided, the system falls back to the configuration file values.

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