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

Set CPU and memory limits using the --cpus and --memory CLI flags to override system defaults defined in config.toml, or modify the [container] table in ~/.config/container/config.toml to change defaults persistently.

Apple Container provides a three-tier configuration system for resource management. You can define CPU and memory constraints through system-wide configuration files, override them per-container using command-line arguments, or set machine-specific baselines for named environments. This layered approach ensures containers receive appropriate resources without requiring repetitive CLI arguments for every invocation.

Understanding the Configuration Hierarchy

The apple/container tooling resolves resource limits through a precedence-based model defined in Sources/ContainerPersistence/ContainerSystemConfig.swift. The system evaluates configuration in this order:

1. System-wide defaults from ~/.config/container/config.toml
2. Per-machine defaults for named container machines
3. Command-line overrides passed to specific commands

When you execute a command like container run, the system first loads the base configuration from ContainerSystemConfig.swift (which defines 4 vCPUs and 1 GiB of memory as defaults), applies any machine-specific settings from the [machine] table, then substitutes explicit --cpus or --memory values to produce the final ContainerConfig object passed to the runtime.

Setting Resource Limits via CLI

The container run and container create commands expose --cpus and --memory flags that temporarily override configuration file settings. These flags accept integer values for CPU cores and human-readable memory strings (e.g., 16g, 512m) parsed by Sources/ContainerPersistence/Measurement+Parse.swift.

# Use system defaults (4 CPUs, 1 GiB)

container run -d my-image

# Override only CPU count

container run -d --cpus 6 my-image

# Override both CPU and memory

container run -d --cpus 8 --memory 16g my-image

Builder VMs and container machines support the same flags with their own default values:

# Builder defaults are typically 2 CPUs, 2 GiB RAM

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

# Create a machine with specific resources

container machine create --cpus 4 --memory 8g dev-machine

Configuring Persistent Defaults in config.toml

To avoid repeating CLI flags, modify the [container] table in ~/.config/container/config.toml. According to docs/container-system-config.md, this file stores system-wide defaults that persist across sessions.

# ~/.config/container/config.toml

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

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

These values override the hardcoded defaults in ContainerSystemConfig.swift (where defaultCPUs = 4 and defaultMemory = "1g" are defined) for all subsequent container operations.

Managing Machine-Specific Resources

Named container machines support independent resource profiles through the [machine] section in config.toml or via the container machine set command documented in docs/container-machine.md.

# Set defaults for a machine named "dev"

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

These settings apply to future container machine create -n dev invocations unless explicitly overridden by CLI flags. This allows you to maintain different resource profiles for development, testing, and production environments.

Summary

• Configuration layers: System defaults (config.toml) → Machine settings ([machine] table) → CLI flags (--cpus, --memory)
• Default values: 4 vCPUs and 1 GiB RAM defined in Sources/ContainerPersistence/ContainerSystemConfig.swift
• CLI syntax: --cpus <int> and --memory <string> (e.g., 16g, 512m)
• Config file location: ~/.config/container/config.toml under the [container] table
• Memory parsing: Human-readable units handled by Measurement+Parse.swift

Frequently Asked Questions

Where are the default CPU and memory values defined?

The default values of 4 vCPUs and 1 GiB of memory are hardcoded in Sources/ContainerPersistence/ContainerSystemConfig.swift within the ContainerSystemConfig struct. These values apply when no configuration file exists and no CLI flags are provided.

What units does the --memory flag accept?

The --memory flag accepts human-readable strings parsed by Sources/ContainerPersistence/Measurement+Parse.swift. Valid formats include 32g (gibibytes), 512m (mebibytes), or 2G (gigabytes). The parser handles both uppercase and lowercase suffixes.

Can I set different limits for the builder VM?

Yes. The container builder start command accepts --cpus and --memory flags to configure the builder VM resources independently from running containers. Builder VMs typically default to 2 CPUs and 2 GiB RAM unless overridden.

How do I change resources for an existing container machine?

Use container machine set -n <machine-name> cpus=<value> memory=<value> to modify default resources for a named machine. These changes affect future instances created with container machine create but do not retroactively modify currently running machines.

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