How to Configure Container Machine Settings in Apple Container

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 only reads them during the next startup cycle. The following parameters are defined in docs/container-machine.md and modeled in 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.

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

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.

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, 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.

# 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 defines the JSON schema that stores these values.

Internally, Swift code accesses this configuration programmatically:

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.

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

No. According to 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.

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