# How to Run a Container on a Specific Network Using Apple Container > Learn to run a container on a specific network with Apple Container. Create an isolated network and attach your container using simple commands. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-05 --- **To run a container on a specific network, first create an isolated network with `container network create `, then attach the container using the `--network ` flag when calling `container run`.** The **Apple Container** framework implements vmnet-based virtual networking to isolate container traffic. When the container system initializes, it automatically provisions a default network named `default` using the CIDR `192.168.64.0/24`. To route a container through a different subnet or bridge, you must explicitly create that network namespace and reference it during container creation. This guide walks through the CLI commands and the underlying implementation in ` apple/container` source code. ## Understanding the vmnet Architecture Under the hood, the CLI communicates network requirements to a runtime service via XPC. When you specify a network, [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) (lines 172–190) constructs a `NetworkBootstrapInfo` struct and passes it to the `RuntimeClient`. The runtime then instantiates a `ContainerNetworkClient` that interfaces with the **container-network-vmnet** helper. This helper creates a `vmnet_network_ref` (implemented in [`Sources/Services/NetworkVmnet/Server/ReservedVmnetNetwork.swift`](https://github.com/apple/container/blob/main/Sources/Services/NetworkVmnet/Server/ReservedVmnetNetwork.swift), lines 57–158) to allocate the virtual interface, returning the assigned IP address, gateway, and MAC address to the container’s sandbox. ## Creating an Isolated Network Before attaching a container, you must provision the network. Use the `container network create` command to establish a new vmnet-based subnet. ```bash # Create a basic network with auto-allocated subnet (192.168.65.0/24 by default) container network create foo ``` For environments requiring specific addressing, define custom IPv4 and IPv6 ranges. According to [`ReservedVmnetNetwork.swift`](https://github.com/apple/container/blob/main/ReservedVmnetNetwork.swift) (lines 136–151), the service validates and stores these subnets in the network-service structs: ```bash # Create a network with explicit subnets container network create bar \ --subnet 192.168.100.0/24 \ --subnet-v6 fd00:1234::/64 ``` Verify the creation by listing available networks: ```bash container network list ``` This outputs the network state and assigned CIDR blocks: ```text NETWORK STATE SUBNET default running 192.168.64.0/24 foo running 192.168.65.0/24 bar running 192.168.100.0/24 ``` ## Running a Container on a Specific Network Once the network exists, attach containers to it using the `--network` flag. The [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) file (lines 172–190) parses this flag into a `NetworkAttachment` struct that includes the network name and optional interface parameters. ```bash # Run a detached container attached to the "foo" network container run -d --name web1 \ --network foo \ --rm ghcr.io/apple/container-demo:web-test ``` The container receives an IP address from the specified subnet (e.g., `192.168.65.2/24`) and uses the network’s gateway for external routing. Inspect the assigned configuration: ```bash container inspect web1 | jq '.networks[0]' ``` Example output: ```json { "address": "192.168.65.2/24", "gateway": "192.168.65.1", "hostname": "web1.test.", "network": "foo" } ``` ### Configuring MAC Addresses and MTU You can fine-tune the container’s network interface by appending parameters to the `--network` flag. Separate each option with a comma: ```bash # Run with a deterministic MAC address container run --network default,mac=02:42:ac:11:00:02 \ --rm alpine:latest \ cat /sys/class/net/eth0/address ``` Available parameters: - **mac=** – Sets a specific MAC address (e.g., `mac=02:42:ac:11:00:02`) - **mtu=** – Specifies the maximum transmission unit in bytes (e.g., `mtu=1500`) ## Publishing Ports on Specific Networks When exposing container services to the host, the `-p` flag binds to the first network specified in `--network`. Traffic routes through that specific subnet’s bridge: ```bash # Publish host port 8080 to container port 8000 via the "foo" network container run -d --name api \ --network foo \ -p 127.0.0.1:8080:8000 \ ghcr.io/apple/container-demo:web-test ``` Requests to `http://127.0.0.1:8080` traverse the `foo` network to reach the container at its assigned IP. ## Platform Limitations on macOS The networking capabilities depend on the host operating system version. In **macOS 15**, the vmnet framework supports only a single active network, meaning the `--network` flag will error if you attempt to attach to a second custom network while the `default` network is active. **macOS 26+** removes this restriction, allowing full multi-network isolation where containers can connect to distinct subnets simultaneously. ## Cleaning Up Networks Delete a network only after detaching all running containers. The `NetworkService` tears down the `vmnet_network_ref` and frees the address space: ```bash container network delete foo ``` Attempting to delete an active network returns an error until all attached containers are stopped or removed. ## Summary - **Create networks first** – Use `container network create` to provision vmnet subnets before running containers. - **Attach with `--network`** – Pass the network name to `container run` or `container create` to assign the container to a specific subnet. - **Customize interfaces** – Append `mac=` and `mtu=` to the network flag for deterministic hardware addresses. - **Check platform support** – Multi-network features require macOS 26+; macOS 15 is limited to the default network. - **Reference implementation** – Core logic resides in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) (XPC messaging) and [`ReservedVmnetNetwork.swift`](https://github.com/apple/container/blob/main/ReservedVmnetNetwork.swift) (vmnet allocation). ## Frequently Asked Questions ### Can I attach a running container to multiple networks? No, each container instance binds to a single network at creation time. The `NetworkBootstrapInfo` struct passed via XPC in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) accepts one network configuration per container. To change networks, you must stop the container and recreate it with a different `--network` flag. ### How do I configure a static IP address for a container? The Apple Container implementation assigns IPs dynamically via the vmnet framework. While you can specify a custom MAC address using `--network foo,mac=...`, static IP assignment is not exposed in the current CLI. The IP allocation occurs inside [`ReservedVmnetNetwork.swift`](https://github.com/apple/container/blob/main/ReservedVmnetNetwork.swift) (lines 57–158) when the vmnet interface is created. ### Why does the `--network` flag fail on macOS 15? macOS 15’s vmnet framework only supports a single active network interface. If the `default` network is running, attempting to specify `--network ` triggers an error because the system cannot provision additional `vmnet_network_ref` instances. Upgrade to macOS 26+ for multi-network support, or stop all containers and delete the default network before using custom networks. ### Where does the network configuration persist? Network definitions are managed by the `NetworkService` daemon and stored in the container system’s data directory. You can inspect the current state using `container network inspect `, which queries the vmnet helper for IPv4/IPv6 subnets, gateway information, and attached container IDs as implemented in [`Sources/Services/Network/Server/NetworkService.swift`](https://github.com/apple/container/blob/main/Sources/Services/Network/Server/NetworkService.swift).