Skip to content

Update documents with note about container-to-host networking. #1482

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jglogan merged 1 commit into from
Apr 30, 2026
Merged

Update documents with note about container-to-host networking. #1482

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/how-to.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,11 @@ Test access using `curl`:

## Access a host service from a container

> [!IMPORTANT]
> Due to macOS security constraints around packet filter rules, this feature has limited functionality:
> - Creating a localhost domain disables Private Relay.
Copy link
Copy Markdown
Contributor

@katiewasnothere katiewasnothere Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit but should we link to what Private Relay is?

Copy link
Copy Markdown
Contributor Author

@jglogan jglogan Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure how stable https://support.apple.com/guide/mac-help/use-icloud-private-relay-mchlecadabe0/mac is (and it's an release-specific link).

> - The local domain packet filter rule is removed on a restart.

Create a DNS domain with `--localhost <ipv4-address>` to make a domain used by a container to access a host service. Any IPv4 address can be used as `<ipv4-address>`, which will be assigned to the domain name in container.

Choose an IP address that is least likely to conflict with any networks or reserved IP addresses in your environment. Reasonably safe address ranges include:
Expand Down
13 changes: 1 addition & 12 deletions docs/technical-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,15 +74,4 @@ In macOS 15, all containers attach to the default vmnet network. The `container

In macOS 15, limitations in the vmnet framework mean that the container network can only be created when the first container starts. Since the network XPC helper provides IP addresses to containers, and the helper has to start before the first container, it is possible for the network helper and vmnet to disagree on the subnet address, resulting in containers that are completely cut off from the network.

Normally, vmnet creates the container network using the CIDR address 192.168.64.1/24, and on macOS 15, `container` defaults to using this CIDR address in the network helper. To diagnose and resolve issues stemming from a subnet address mismatch between vmnet and the network helper:

- Before creating the first container, scan the output of the command `ifconfig` for a bridge interface named similarly to `bridge100`.
- After creating the first container, run `ifconfig` again, and locate the new bridge interface to determine the container subnet address.
- Run `container ls` to check the IP address given to the container by the network helper. If the address corresponds to a different network:
- Run `container system stop` to terminate the services for `container`.
- Using the macOS `defaults` command, update the default subnet value used by the network helper process. For example, if the bridge address shown by `ifconfig` is 192.168.66.1, run:
```bash
defaults write com.apple.container.defaults network.subnet 192.168.66.1/24
```
- Run `container system start` to launch services again.
- Try running the container again and verify that its IP address matches the current bridge interface value.
Normally, vmnet creates the container network using the CIDR address 192.168.64.1/24, and on macOS 15, `container` defaults to using this CIDR address in the network helper. If your containers have no network access on macOS 15, see [All networking fails on macOS 15](troubleshooting.md#all-networking-fails-on-macos-15) for diagnosis and remediation steps.