How to Configure Resource Limits (CPU, Memory) for Containers in apple/container

Resource limits in the apple/container project are configured through a hierarchical system: system-wide defaults defined in ContainerSystemConfig.swift, persistent settings in config.toml, and immediate overrides via the --cpus and --memory command-line flags.

The apple/container repository provides a Swift-based container runtime that manages computational resources through a structured configuration hierarchy. Understanding how to configure CPU and memory resource limits ensures optimal performance for containerized workloads while preventing resource contention on the host system.

Understanding the Resource Configuration Hierarchy

The container CLI determines resource allocation through three distinct layers, applied in order of precedence:

1. System-wide defaults – Hardcoded values and config.toml settings that apply to all containers
2. Per-machine defaults – Configuration specific to named container machines
3. Command-line overrides – Immediate flags that supersede all other settings

This layered approach allows you to set sensible defaults while retaining flexibility for specific workloads.

System-Wide Defaults in ContainerSystemConfig.swift

Default resource limits are defined in Sources/ContainerPersistence/ContainerSystemConfig.swift, where the ContainerSystemConfig struct specifies defaultCPUs = 4 and defaultMemory = "1g". Without explicit configuration, every container receives 4 vCPUs and 1 GiB of RAM.

You can customize these defaults by creating a config.toml file in your configuration directory:

# ~/.config/container/config.toml

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

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

The system configuration schema is documented in docs/container-system-config.md, which details the [container] table structure for persistent defaults.

Overriding Limits via CLI Commands

The container run and container create commands expose --cpus and --memory flags that replace system defaults for specific container instances. These flags accept integer values for CPUs and human-readable strings (e.g., 32g, 512m) for memory.

# 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

According to docs/how-to.md and docs/command-reference.md, these flags are parsed during command execution and encoded into a ContainerConfig object before passing to the low-level runtime.

Configuring Builder and Machine VM Resources

Resource limits also apply to virtual machines used for building images and running persistent machines. The container builder start command accepts the same --cpus and --memory flags, with builder defaults typically set to 2 CPUs and 2 GiB RAM.

# Configure builder VM with 6 CPUs and 8 GiB RAM

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

For named container machines, use the container machine set command to establish persistent defaults that apply to future container machine create operations:

# Set defaults for a machine named "dev"

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

These per-machine settings, documented in docs/container-machine.md, are stored in the [machine] section of config.toml and apply unless overridden by CLI flags.

How Memory Values Are Parsed

The container CLI accepts human-readable memory strings like 32g, 512m, or 1.5gb. These values are parsed by Sources/ContainerPersistence/Measurement+Parse.swift, which converts the string representations into internal memory measurements before allocation. This parsing supports both binary (GiB, MiB) and decimal (GB, MB) suffixes, though the default configuration uses 1g to represent 1 GiB.

Summary

• Default values are defined in Sources/ContainerPersistence/ContainerSystemConfig.swift as 4 CPUs and 1 GiB memory
• Persistent configuration is stored in ~/.config/container/config.toml under the [container] section
• CLI overrides use --cpus and --memory flags with container run, container create, and container builder start
• Machine-specific defaults can be set via container machine set and stored in the [machine] table
• Memory parsing is handled by Measurement+Parse.swift, supporting human-readable formats like 16g or 512m

Frequently Asked Questions

What is the default CPU and memory allocation for new containers?

By default, the container CLI assigns 4 vCPUs and 1 GiB of memory to every new container. These values are hardcoded in Sources/ContainerPersistence/ContainerSystemConfig.swift as defaultCPUs = 4 and defaultMemory = "1g", and they apply unless you specify alternatives in config.toml or via command-line flags.

How do I permanently change resource defaults for all containers?

Create a config.toml file in your configuration directory (typically ~/.config/container/) and set values under the [container] table. For example, setting cpus = 2 and memory = "2g" establishes new system-wide defaults that apply to all subsequently created containers unless overridden by CLI flags.

Can I set different resource limits for builder VMs versus runtime containers?

Yes. While runtime containers use the [container] table defaults, builder VMs can be configured separately using the --cpus and --memory flags with container builder start. Additionally, persistent machines managed via container machine can have specific defaults set using container machine set, which stores configuration in the [machine] section of config.toml.

What format does the --memory flag accept?

The --memory flag accepts human-readable size strings such as 512m, 2g, 16gb, or 1.5gi. These strings are parsed by Sources/ContainerPersistence/Measurement+Parse.swift, which converts them into internal memory measurements. While the default configuration uses g to denote gibibytes (GiB), the parser supports various suffixes for both binary and decimal units.

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