How to Set CPU and Memory Limits for Containers in Apple Container

Configure container resource limits using the --cpus and --memory CLI flags for per-container overrides, or set persistent defaults in ~/.config/container/config.toml under the [container] section.

The Apple Container framework manages resource allocation through a layered configuration system implemented in Sources/ContainerPersistence/ContainerSystemConfig.swift. You can constrain CPU and memory via command-line arguments, configuration files, or machine-specific defaults, with values cascading from system settings through CLI flags to the final ContainerConfig object passed to the runtime.

Understanding the Configuration Hierarchy

The framework determines final resource values by evaluating three configuration layers in order of precedence:

1. System-wide defaults – Stored in ~/.config/container/config.toml under the [container] table, as documented in docs/container-system-config.md
2. Machine-specific defaults – Set via container machine set or the [machine] section in config.toml per docs/container-machine.md
3. CLI overrides – Provided via --cpus and --memory flags at runtime, documented in docs/command-reference.md

According to Sources/ContainerPersistence/ContainerSystemConfig.swift, the hardcoded system defaults initialize to defaultCPUs = 4 and defaultMemory = "1g", meaning containers receive 4 virtual CPUs and 1 GiB of RAM unless explicitly configured otherwise.

Configuring System-Wide Defaults

Create or edit ~/.config/container/config.toml to establish baseline resources for all containers on your system. The [container] table defines values that apply when you omit CLI flags.

# ~/.config/container/config.toml

[container]
cpus = 2               # Default to 2 CPUs per container

memory = "2g"         # Default to 2 GiB RAM per container

The framework parses these values using Sources/ContainerPersistence/Measurement+Parse.swift, which handles human-readable memory formats like "16g" or "512m". These settings persist across reboots and apply to every container run invocation unless overridden by flags, as shown in docs/how-to.md.

Overriding Limits via Command-Line Flags

Override defaults for individual containers using the --cpus and --memory flags with container run or container create. These flags replace the defaults for the specific container you are launching.

# Use system defaults (4 CPUs, 1 GiB)

container run -d my-image

# Override CPU count only

container run -d --cpus 6 my-image       # → 6 CPUs, 1 GiB RAM

# Override both CPU and memory

container run -d --cpus 8 --memory 16g my-image   # → 8 CPUs, 16 GiB RAM

The CLI processor reads the system config, applies any per-machine defaults, then substitutes explicit --cpus and --memory values into the ContainerConfig object before passing it to the low-level container runtime.

Configuring Builder and Machine Resources

Builder VMs and container machines maintain separate resource defaults that you can modify independently from standard container defaults.

Builder VM Configuration

The builder VM defaults to 2 CPUs and 2 GiB RAM according to the BuildConfig implementation. Adjust these resources when starting the builder:

container builder start --cpus 6 --memory 8g

Container Machine Configuration

Set persistent defaults for named machines using the container machine set command. These values apply to future container machine create operations for that specific machine name.

# Set defaults for a machine named "dev"

container machine set -n dev cpus=4 memory=8G

Future invocations of container machine create -n dev inherit these defaults unless CLI flags specify otherwise. Per-machine configuration resides in the [machine] section of config.toml as documented in docs/container-machine.md.

Summary

• Default values: 4 CPUs and 1 GiB RAM defined in Sources/ContainerPersistence/ContainerSystemConfig.swift
• Configuration file: Edit ~/.config/container/config.toml under [container] for system-wide defaults
• Memory parsing: Human-readable strings (e.g., "32g", "512m") processed by Measurement+Parse.swift
• CLI overrides: Use --cpus and --memory with container run, container create, or container machine create
• Builder defaults: 2 CPUs and 2 GiB RAM unless specified with container builder start --cpus and --memory
• Machine defaults: Use container machine set to configure named machine templates

Frequently Asked Questions

What are the default CPU and memory limits for new containers?

According to Sources/ContainerPersistence/ContainerSystemConfig.swift, the system initializes with defaultCPUs = 4 and defaultMemory = "1g". If you never specify limits in config.toml or via CLI flags, every container receives 4 virtual CPUs and 1 GiB of RAM.

How do I set persistent defaults for all containers on my system?

Edit ~/.config/container/config.toml and add a [container] section with cpus and memory keys. For example, setting cpus = 2 and memory = "2g" changes the baseline from 4 CPUs/1 GiB to 2 CPUs/2 GiB for all future containers unless overridden by command-line flags.

Can I override resource limits for a single container without changing the defaults?

Yes, use the --cpus and --memory flags with container run or container create. These flags immediately override both system defaults and machine-specific settings for that specific container instance, encoding the final values into the ContainerConfig object passed to the runtime.

How do I configure resources for the builder VM separately from regular containers?

The builder VM uses separate defaults (2 CPUs, 2 GiB) defined in BuildConfig. Use container builder start --cpus <value> --memory <value> to override these temporarily. For persistent builder machine configuration, use container machine set to define defaults for the specific builder machine name.

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