How to Set Memory and CPU Limits for a Container in apple/container

You configure CPU and memory limits through a three-layer hierarchy: system-wide defaults defined in ContainerSystemConfig.swift (4 CPUs and 1 GiB), persistent values in ~/.config/container/config.toml, and immediate overrides via the --cpus and --memory CLI flags.

The apple/container project determines resource allocation by layering configuration sources. Understanding how Sources/ContainerPersistence/ContainerSystemConfig.swift defines defaults, how config.toml persists preferences, and how command-line arguments override both ensures precise resource control without repetitive typing.

Configuration Hierarchy and Precedence

Resource limits resolve in strict order of specificity: CLI flags override per-machine settings, which override the system-wide [container] table in config.toml.

System-Wide Defaults

When you never specify limits, the system falls back to hardcoded defaults in Sources/ContainerPersistence/ContainerSystemConfig.swift:

• defaultCPUs = 4
• defaultMemory = "1g"

These values populate the ContainerConfig struct and apply to every new container unless superseded by configuration files or flags. According to the source, these defaults translate to 4 vCPUs and 1 GiB of RAM per container instance.

Per-Machine Overrides

For container machines (VMs that host containers), the [machine] section in config.toml can establish defaults tied to specific machine names. The container machine set command writes these values, which persist for future container machine create invocations. For example, setting cpus=4 memory=8G on a machine named "dev" causes all subsequent creations of that machine to inherit those resources unless CLI flags intervene.

Command-Line Overrides

The highest precedence belongs to explicit flags. The container run and container create commands expose --cpus and --memory parameters that completely replace defaults for that specific invocation. The same flags work for container builder start (configuring the build VM) and container machine create (configuring new machine VMs).

Setting Resource Limits in Practice

Overriding Defaults with CLI Flags

Use the --cpus and --memory flags to specify resources for individual containers:

# 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

As implemented in the CLI parsing logic, these flags accept integer CPU counts and human-readable memory strings (e.g., 16g, 32g).

Configuring Persistent Defaults in config.toml

To change defaults for all containers without typing flags repeatedly, edit ~/.config/container/config.toml:

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

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

The Sources/ContainerPersistence/Measurement+Parse.swift file handles parsing of these string values, supporting human-readable units like "1g", "2g", or "512m".

Adjusting Builder and Machine Resources

Build environments and container machines support the same resource parameters with their own default scopes:

Builder VM:

# Start builder with 6 CPUs and 8 GiB RAM (overrides BuildConfig defaults)

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

Container Machines:

# Set persistent defaults for machine "dev"

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

Future invocations of container machine create -n dev inherit these settings unless explicitly overridden.

Key Implementation Files

• Sources/ContainerPersistence/ContainerSystemConfig.swift: Defines defaultCPUs, defaultMemory, and the ContainerConfig struct.
• Sources/ContainerPersistence/Measurement+Parse.swift: Parses memory strings (e.g., "32g") into byte values.
• docs/container-system-config.md: Documents the config.toml schema and [container] table.
• docs/command-reference.md: Reference for --cpus and --memory flag syntax.

Summary

• Default resources are 4 CPUs and 1 GiB RAM, defined in ContainerSystemConfig.swift.
• Configuration file at ~/.config/container/config.toml stores system-wide and per-machine defaults under the [container] and [machine] tables.
• CLI flags --cpus and --memory override all other settings for container run, container create, container builder start, and container machine create.
• Memory values use human-readable strings parsed by Measurement+Parse.swift (e.g., "16g", "512m").

Frequently Asked Questions

What are the default CPU and memory limits?

The system defaults to 4 vCPUs and 1 GiB of RAM for every container. These values originate from defaultCPUs = 4 and defaultMemory = "1g" in Sources/ContainerPersistence/ContainerSystemConfig.swift.

Where is the container configuration file located?

The configuration file resides at ~/.config/container/config.toml. This file stores the [container] table for system-wide defaults and the [machine] table for per-machine resource preferences.

Can I set CPU and memory limits for the builder VM?

Yes. The container builder start command accepts --cpus and --memory flags to configure the build environment. For example, container builder start --cpus 6 --memory 8g allocates 6 CPUs and 8 GiB RAM to the builder instance.

What units does the memory parameter accept?

The --memory flag and config.toml values accept human-readable strings such as 1g, 2g, or 512m. The Sources/ContainerPersistence/Measurement+Parse.swift module parses these strings into byte measurements for the runtime.

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