# How to Configure Container Machine Settings in Apple Container

> Configure container machine settings like CPU and memory in Apple Container using the container machine set command. Restart the machine to apply these changes.

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

---

**Use the `container machine set` command to adjust CPU, memory, and virtualization parameters, then restart the machine for changes to take effect.**

The **Apple Container** project provides a lightweight Linux environment that runs on macOS using OCI images with persistent storage. When you need to configure container machine settings, you modify key-value pairs that the **ServiceManager** component reads from a JSON file during machine initialization. These settings persist in `~/.container/machines/<name>/config.json` and control resource allocation, storage mounting, and virtualization capabilities.

## Available Configuration Options

The `container machine set` command writes settings to disk immediately, but the **ServiceManager** component in [`Sources/ContainerPlugin/ServiceManager.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/ServiceManager.swift) only reads them during the next startup cycle. The following parameters are defined in [`docs/container-machine.md`](https://github.com/apple/container/blob/main/docs/container-machine.md) and modeled in [`Sources/ContainerPlugin/PluginConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/PluginConfig.swift).

### CPU and Memory Allocation

Control compute resources with the `cpus` and `memory` parameters.

- **CPU count** (`cpus`): Sets the number of virtual CPUs allocated to the machine.
- **Memory size** (`memory`): Specifies RAM allocation using standard size suffixes like `G` for gigabytes.

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

```

### Home Directory Mount Mode

The **home-mount mode** (`homeMount`) determines how macOS shares your home directory with the container. By default, the machine maps `$HOME` on macOS to `/Users/<username>` inside the container for seamless file sharing.

Available modes include:

- `rw`: Read-write access (default)
- `ro`: Read-only access
- `none`: Disables the mount entirely

```bash
container machine set -n dev homeMount=ro

```

### Nested Virtualization and Custom Kernels

Enable advanced virtualization features using the `virtualization` and `kernel` settings.

**Nested virtualization** (`virtualization`) exposes `/dev/kvm` to the container, allowing you to run KVM guests inside the machine. This requires Apple Silicon M3+ on macOS 15+ and a Linux kernel compiled with `CONFIG_KVM=y`. The default kernel shipped with Apple Container does not include KVM support, so you must provide a custom binary.

**Custom kernel** (`kernel`) specifies an absolute path to a replacement kernel binary. An empty value resets to the bundled kernel.

```bash
container machine set -n dev virtualization=true kernel=/opt/kernels/vmlinux-kvm

```

## Applying Configuration Changes

Configuration changes do not take effect on running machines. According to the implementation in [`Sources/ContainerPlugin/ServiceManager.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/ServiceManager.swift), the system reads the configuration file only during the machine initialization sequence.

To apply new settings:

1. Stop the running machine.
2. Start the machine again to trigger the ServiceManager to allocate resources and recreate bind mounts.

```bash

# Stop the machine

container machine stop dev

# Start and verify the new configuration

container machine run -n dev uname -a

```

## Configuration File Internals

When you run `container machine set`, the command writes to `~/.container/machines/<name>/config.json`. The **PluginConfig** data model in [`Sources/ContainerPlugin/PluginConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/PluginConfig.swift) defines the JSON schema that stores these values.

Internally, Swift code accesses this configuration programmatically:

```swift
import ContainerPlugin

let config = try PluginConfig.load(for: "dev")
print("CPUs:", config.cpus ?? "default")
print("Memory:", config.memory ?? "default")
print("KVM enabled:", config.virtualization ?? false)

```

This structure ensures that both the CLI and internal components use the same persistence layer for machine settings.

## Summary

- **Use `container machine set`** with key-value syntax to configure container machine settings including CPU count, memory size, home-mount mode, and virtualization.
- **Persist changes** in `~/.container/machines/<name>/config.json` as defined by the PluginConfig model.
- **Restart required** — the ServiceManager reads configuration only during machine startup, so you must stop and start the machine to apply changes.
- **Nested virtualization** requires a custom KVM-enabled kernel and modern Apple Silicon hardware.

## Frequently Asked Questions

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

The configuration is stored as JSON in `~/.container/machines/<name>/config.json`. You can view this file directly to see current CPU, memory, and mount settings. Alternatively, use the Swift PluginConfig API to load and inspect the configuration programmatically as implemented in [`Sources/ContainerPlugin/PluginConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/PluginConfig.swift).

### Can I change container machine settings while the machine is running?

No. According to [`docs/container-machine.md`](https://github.com/apple/container/blob/main/docs/container-machine.md), settings are written to disk immediately when you run `container machine set`, but they only take effect after you stop and restart the machine. The ServiceManager component reads the configuration file during the initialization phase, not during runtime.

### What kernel do I need for nested virtualization?

You must provide a custom Linux kernel compiled with `CONFIG_KVM=y` using the `kernel` setting. The default kernel bundled with Apple Container does not include KVM support. Additionally, nested virtualization requires Apple Silicon M3+ and macOS 15 or later to function properly.

### How do I disable the home directory mount completely?

Set `homeMount=none` using the configuration command. This prevents the automatic mapping between your macOS home directory and the container's `/Users/<username>` path, isolating the container filesystem from your host home directory.