How to Manage Container Machine Resources (CPU, Memory, and Home Mounts) in Apple Container

You manage container machine resources in Apple Container by using the container machine set command to modify CPU count, memory allocation, and home-mount mode in the persistent MachineConfig, then applying changes after a stop/start cycle.

Container machines in the apple/container repository provide persistent Linux environments on macOS, and their resource limits are configurable without recreating the machine. The configuration is stored in a MachineConfig value that persists on disk and is read by the container runtime at boot time, allowing you to fine-tune CPU, memory, and home-directory mount behavior.

Understanding MachineConfig Structure

The MachineConfig struct in Sources/ContainerPersistence/MachineConfig.swift defines the schema for container machine resources. It stores three primary settable keys enumerated in MachineConfig.settableKeys: cpus, memory, and homeMount (or home-mount in CLI usage). These keys are validated during parsing and persisted to disk, with the runtime applying them on the next boot cycle.

Configuring CPU Allocation

Default CPU Settings

By default, a container machine advertises half of the host’s physical processors to the Linux kernel, with a minimum of 4 virtual CPUs. This default is defined by MachineConfig.defaultCPUs in Sources/ContainerPersistence/MachineConfig.swift (lines 30-33). The cpus field accepts an integer value representing the exact number of virtual CPUs to expose.

Setting CPU Count via CLI

Use the container machine set command to modify CPU allocation. The change persists immediately but only takes effect after the machine stops and restarts.

# Set CPU count to 4

container machine set -n dev cpus=4

# Verify current configuration

container machine inspect dev

According to docs/container-machine.md (lines 63-70), the updated CPU count appears in the output of container machine inspect and becomes active following the next stop/start cycle.

Managing Memory Limits

Memory Size Defaults

Memory allocation is stored as a MemorySize value in bytes. The default configuration uses half of the host’s physical memory, with a floor of 1 GiB, as implemented in Sources/ContainerPersistence/MachineConfig.swift (lines 34-38).

Human-Readable Memory Syntax

The memory key accepts human-readable strings such as 2G, 512M, or 8G, which MemorySize parses into byte values (lines 70-72). This allows intuitive configuration without manual byte calculation.

# Allocate 8 GiB of memory

container machine set -n dev memory=8G

# Allocate 512 MiB

container machine set -n dev memory=512M

Controlling Home Directory Mounts

The homeMount (or home-mount) enum controls whether and how the host’s $HOME directory appears inside the container at /Users/<username>. The implementation in Sources/ContainerPersistence/MachineConfig.swift (lines 40-47) supports three modes:

• rw (default): Mounts the home directory read-write, allowing bidirectional file synchronization.
• ro: Mounts the home directory read-only, protecting host files from modification inside the container.
• none: Omits the home directory mount entirely, isolating the container filesystem from the host home directory.

# Set read-only home mount

container machine set -n dev home-mount=ro

# Remove home mount entirely

container machine set -n dev home-mount=none

As documented in docs/container-machine.md (lines 73-74), this setting determines the visibility and mutability of host user directories within the Linux environment.

Applying Configuration Changes

Resource changes do not apply to running machines immediately. You must stop and restart the machine for the new MachineConfig values to take effect.

# Apply multiple resource changes at once

container machine set -n dev cpus=2 memory=4G home-mount=none

# Stop the machine to prepare for configuration application

container machine stop dev

# Start and verify CPU count

container machine run -n dev -- nproc

# Verify memory allocation

container machine run -n dev -- cat /proc/meminfo | grep MemTotal

The MachineConfig is re-read from disk during the boot sequence, applying your persisted CPU, memory, and mount settings.

Programmatic Configuration with MachineConfig

For programmatic usage, the MachineConfig.with(_:) helper method (lines 49-78 in Sources/ContainerPersistence/MachineConfig.swift) merges a dictionary of key/value strings into a new MachineConfig instance. The CLI set sub-command ultimately invokes this method after validation, allowing direct manipulation of the configuration structure in Swift code.

// Example conceptual usage of the programmatic API
let updatedConfig = try existingConfig.with([
    "cpus": "4",
    "memory": "8G",
    "home-mount": "ro"
])

Summary

• CPU Allocation: Set via cpus key as an integer; defaults to half host processors (minimum 4).
• Memory Allocation: Set via memory key with human-readable values (e.g., 8G, 512M); defaults to half host memory (minimum 1 GiB).
• Home Mount: Set via home-mount key with values ro, rw, or none; defaults to rw.
• Persistence: Changes are stored in Sources/ContainerPersistence/MachineConfig.swift and written to disk immediately.
• Activation: All resource changes require a container machine stop followed by container machine run to take effect.

Frequently Asked Questions

How do I check the current resource configuration of a container machine?

Run container machine inspect <name> to output the current MachineConfig as JSON. This displays the active CPU count, memory size in bytes, and home-mount mode persisted on disk.

Why don’t my resource changes apply immediately?

The container machine reads MachineConfig only at boot time. While the container machine set command updates the persisted configuration instantly, the running Linux kernel retains the previous CPU and memory limits until you execute container machine stop followed by container machine run or container machine start.

What is the minimum memory I can allocate to a container machine?

The MemorySize validation enforces a minimum of 1 GiB (1073741824 bytes). Attempts to set values below this threshold will fail validation in MachineConfig.with(_:), preventing the creation of unusable machines.

Can I mount the home directory as read-only while keeping other resources writable?

Yes. The home-mount=ro setting is independent of CPU and memory configuration. You can combine read-only home mounts with any CPU count and memory size, allowing flexible security postures where host files are protected while the container retains full computational resources.

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