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

> Learn how to create isolated container networks with the Apple Container CLI. Achieve kernel-level isolation using independent vmnet bridges for enhanced security and control.

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

---

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

```sh
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`](https://github.com/apple/container/blob/main/docs/how-to.md):

```sh
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:

```sh
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):

```sh
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:

```sh
container network list

```

Delete an empty network:

```sh
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:

```sh
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:

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