How to Create an Isolated Network for Containers with the Apple Container CLI

Create user-defined networks with container network create <name> and attach containers using --network <name> to establish kernel-level isolation through independent vmnet bridges.

The Apple Container system leverages the macOS vmnet framework to provide virtualized networking for containers. By default, all containers attach to a shared network named default that lacks isolation capabilities on macOS 15 and later. To establish true network isolation with separate IPv4/IPv6 subnets and MAC address spaces, you must create user-defined networks using the Apple Container CLI.

Understanding Network Isolation Architecture

According to the apple/container source code, network isolation is enforced at the kernel level by the vmnet framework. When you execute container system start, the system automatically instantiates a default vmnet network using a shared bridge. As documented in docs/technical-overview.md, macOS 15 restricts this default network to a single shared segment where containers cannot communicate directly with each other. True isolation requires the XPC helper container-network-vmnet to allocate independent virtual bridges for each user-defined network, ensuring traffic remains confined to its assigned subnet.

Creating an Isolated Network

The container network create command instructs the runtime to provision a new virtual network. As implemented in Sources/Services/ContainerAPIService/Client/NetworkClient.swift, this process allocates a unique bridge and configures DHCP services for IP address assignment.

Basic Network Creation

Create an isolated network with automatically generated subnets:

container network create foo

Custom Subnet Configuration

Specify explicit CIDR ranges using the --subnet and --subnet-v6 flags. This approach is documented in docs/how-to.md:

container network create foo --subnet 192.168.100.0/24 --subnet-v6 fd00:1234::/64

Attaching Containers to Isolated Networks

When running containers, specify the --network flag to attach to your isolated network. The container runtime requests an IP address from the network's DHCP service, and kernel routing tables confine traffic to that specific bridge. No ARP or IPv6 Neighbor Discovery traffic crosses between networks, preventing containers on different networks from seeing each other.

Run a container on the isolated network:

container run -d --name my-web-server --network foo --rm web-test

Publish a port while maintaining network isolation (the port binds to the host interface but the container remains isolated):

container run -d --name app --network foo -p 8080:80 nginx

Listing and Managing Networks

Inspect all user-defined networks and remove unused ones. Note that container network delete requires the network to be empty of container attachments, as verified by the integration tests in Tests/IntegrationTests/Utilities/ContainerFixture+NetworkHelpers.swift.

List networks:

container network list

Delete an empty network:

container network delete foo

Advanced Configuration Options

Host-Only Internal Networks

Create a network with no external routing outside the host by adding the --internal flag. This configuration creates a completely isolated segment accessible only from the macOS host:

container network create internal-only --internal

Persistent Configuration Defaults

Customize default subnet ranges for future networks by editing ~/.config/container/config.toml. These settings apply to all subsequently created networks that do not specify explicit subnets:

[network]
defaultSubnet = "192.168.64.0/24"
defaultSubnetV6 = "fd00:abcd::/64"

Summary

• User-defined networks operate on independent virtual bridges with isolated IPv4/IPv6 subnets and MAC address spaces
• Kernel-level isolation prevents ARP and IPv6 Neighbor Discovery traffic from crossing network boundaries
• The XPC helper container-network-vmnet handles bridge allocation and DHCP configuration as implemented in Sources/Services/ContainerAPIService/Client/NetworkClient.swift
• Use --internal to create host-only networks with no external routing
• Configure default subnets in ~/.config/container/config.toml for persistent environment settings

Frequently Asked Questions

Can containers on different isolated networks communicate?

No. According to docs/technical-overview.md, each network exists on its own virtual bridge managed by the vmnet framework. Separate kernel routing tables ensure that Layer 2 traffic, including ARP and IPv6 Neighbor Discovery packets, cannot traverse network boundaries. Containers attached to different networks have no connectivity to each other.

What happens if I run a container without specifying a network?

The container automatically attaches to the default network created during container system start. This default network provides limited isolation on macOS 15 and later, where the vmnet framework restricts all default containers to a single shared segment that prevents direct container-to-container communication.

Why does container network delete fail for an empty network?

The delete command requires the network to have zero active container attachments, including stopped containers that may retain network references. Verify no containers are using the network with container ps -a, or force remove containers before attempting deletion.

Where does the Apple Container CLI store network configuration?

Network creation logic is implemented in Sources/Services/ContainerAPIService/Client/NetworkClient.swift, while user-specific defaults are stored in ~/.config/container/config.toml. Runtime network state and bridge allocation are managed by the container-network-vmnet XPC helper.

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