Limitations of Container on macOS 15: Network and Resource Constraints Explained

The container tool on macOS 15 cannot create multiple isolated networks, lacks full memory ballooning support, and restricts inter-container communication due to constraints in the underlying vmnet framework.

The container CLI from the apple/container repository provides lightweight virtualization using Apple’s Virtualization framework. While compatible with macOS 15 (Catalina and newer), several critical features are either missing or behave differently because system services, particularly vmnet, lack capabilities available in macOS 26.

Network Isolation and Inter-Container Communication

On macOS 15, the Virtualization framework’s vmnet implementation supports only a single isolated network instance, which fundamentally restricts how containers communicate.

Single Isolated Network Constraint

According to docs/technical-overview.md, the vmnet framework on macOS 15 can only create one isolated network. All containers attach to this default network, and inter-container communication—such as a client container reaching a server container—is impossible. This limitation is enforced by the XPC helper implementation in Sources/ContainerNetworkServer/*, which performs macOS-specific checks before allowing network operations.

Unavailable Network Subcommands

The container network subcommands and the --network flag are explicitly disabled on macOS 15. Attempting to use these features returns an immediate error:

# Listing custom networks fails

container network list
#> error: 'container network' sub-commands are not supported on macOS 15

# Attaching to a custom network fails

container run --network customnet nginx
#> error: the '--network' option is unavailable on macOS 15

IP Address Allocation and Network Helper Dependency

Container networking on macOS 15 requires strict initialization order. The network helper must run before the first container starts, or IP allocation fails entirely.

Network Helper Timing Requirements

As documented in docs/technical-overview.md, if the network helper starts after the first container or disagrees with vmnet on the subnet configuration, containers may start successfully but receive no IP address. You can verify this state by inspecting the container:

# Check for null IP address indicating allocation failure

container inspect mycontainer | grep IPAddress
#> "IPAddress": null   # <- indicates the network helper could not assign an address

This behavior is specific to macOS 15 and does not occur on macOS 26.

Memory Management and Resource Constraints

macOS 15’s Virtualization framework provides only partial support for memory reclamation and enforces strict default resource limits.

Memory Ballooning Limitations

The framework on macOS 15 only partially supports memory ballooning. Freed pages inside the VM are not returned to the host, meaning long-running, memory-intensive workloads can cause persistent host-side memory pressure. You may need to restart containers to reclaim RAM on the host system.

Default Resource Limits

According to docs/how-to.md, default VM limits are 1 GiB of RAM and 4 CPUs. On macOS 15, you cannot override these defaults without explicitly passing the --memory and --cpus flags:

# Explicitly allocate 8GB RAM and 6 CPU cores

container run --memory 8g --cpus 6 hello-world

Without these flags, workloads requiring more than the defaults will be throttled by the Virtualization framework.

Diagnostic and Recovery Tools

When the network helper becomes stuck or misconfigured on macOS 15, the repository provides a cleanup utility. The script scripts/ensure-container-stopped.sh terminates the network helper and cleans up vmnet interfaces, which is useful for recovering from the "no IP address" state without rebooting the host.

Summary

• Network isolation: Only one isolated network exists; containers cannot communicate with each other on macOS 15.
• Custom networks: The container network subcommands and --network flag are disabled and return errors.
• IP allocation: The network helper must start before the first container; otherwise containers receive null IP addresses.
• Memory management: Partial memory ballooning support means freed pages are not returned to the host, potentially causing memory pressure.
• Resource limits: Defaults are locked at 1 GiB RAM and 4 CPUs; use --memory and --cpus flags to override on macOS 15.

Frequently Asked Questions

Can containers communicate with each other on macOS 15?

No. Due to vmnet framework limitations in macOS 15, the container tool can only create a single isolated network. Inter-container communication is impossible on this version, though it works on macOS 26.

Why does my container show a null IP address?

This occurs when the network helper starts after the first container or when the helper disagrees with vmnet on the subnet configuration. The network helper must be running before you create the first container. Check docs/troubleshooting.md for recovery steps, or use scripts/ensure-container-stopped.sh to reset the network state.

How do I increase memory and CPU limits on macOS 15?

You must explicitly pass the --memory and --cpus flags when running containers. The defaults are 1 GiB RAM and 4 CPUs, and automatic resource detection is not supported on macOS 15. For example: container run --memory 8g --cpus 6 myimage.

Should I upgrade to macOS 26 to avoid these limitations?

Yes. The container tool is designed for macOS 26 where the Virtualization framework supports multiple networks, full memory ballooning, and better resource management. macOS 15 support is intended for simple, single-container workloads only.

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