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

> Easily manage Apple Container machine resources like CPU memory and home mounts using the container machine set command Streamline your development workflow today

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-29

---

**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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.

```bash

# 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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.

```bash

# 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`](https://github.com/apple/container/blob/main/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.

```bash

# 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`](https://github.com/apple/container/blob/main/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.

```bash

# 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`](https://github.com/apple/container/blob/main/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.

```swift
// 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`](https://github.com/apple/container/blob/main/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.