DOCKER

Networks and ports

Containers in Kiri get Docker’s networks: a default bridge, the networks you create, and host and none. Ports you publish with -p open on the Mac, and every container can reach the Mac back as host.docker.internal.

Networks

Three networks always exist:

Network	What a container gets
`bridge`	The default. Its own address on `172.17.0.0/16` and a way out to the internet. Names don’t resolve here, as in Docker.
`host`	The VM’s network, not the Mac’s: no address of its own.
`none`	Only loopback. It can’t publish ports.

docker network create makes a user network: a bridge of its own with the next free /16 from 172.18.0.0 up and its gateway at .1. Kiri supports only the bridge driver. User networks are saved, so they’re still there after a daemon restart, and docker network ls, inspect, rm and prune work on them.

Kiri’s window lists networks under Networks, with their driver and subnet. You can remove the ones you made there.

DNS by name on user networks

On a user network, containers find each other by name. Each user network has a small DNS server on its gateway address. It answers with the address of a container on that network, looked up by the container’s name, any --network-alias, or its hostname. Every other name is passed on to the VM’s resolver.

Two containers on a user network. web asks the network's DNS server for db, gets db's address, and connects to it directly over the bridge.

docker network create appnet
docker run -d --name db --network appnet -e POSTGRES_PASSWORD=dev postgres
docker run --rm --network appnet postgres pg_isready -h db

A container can be on more than one network. docker network connect appnet web adds one to a container, optionally with --alias, and docker network disconnect takes it away. A container on host or none can’t be connected to another network.

Publishing ports

-p 8080:80 publishes the container’s port 80 on the Mac’s port 8080, and -p 8080:80/udp does the same for UDP. Leave out the host port (-p 80) for any free one; -P publishes every port the image declares with EXPOSE, or you add with --expose, each on a free port. docker port and docker ps show what was chosen.

Kiri’s daemon opens a listener on the Mac for each published port. Each connection gets its own vsock stream into the VM, where the guest agent connects to the container and relays the bytes. No root is needed, and nothing depends on how macOS routes the VM’s network.

A published port. The listener is on the Mac; each connection is carried into the VM over vsock and relayed to the container. Without an address, -p listens on every interface, so other machines on your network can connect too.

A --network host container has no address of its own, so -p relays to the port it listens on in the VM. That is how you reach it from the Mac.

Instead of a port number, you can also use a container’s name: http://web.kiri.localhost reaches the HTTP port of a running container called web, with no -p needed, and so does http://web.kiri.local once you turn it on. See Domain names.

Reaching the Mac from a container

Every container can reach the Mac as host.docker.internal (also host.kiri.internal and gateway.docker.internal). Connections to it go to services listening on the Mac’s loopback, so a dev server on localhost:5173 on the Mac is host.docker.internal:5173 inside a container.

docker run --rm curlimages/curl http://host.docker.internal:5173

--add-host name:ip adds a line to the container’s /etc/hosts, and --add-host name:host-gateway points a name of your own at the Mac.

Not supported

Network drivers other than bridge.
--network container:<name>.
Protocols other than TCP and UDP on -p.

Domain namesReach containers at name.kiri.local, no ports needed.HTTPSThe same names over HTTPS, with Kiri’s own certificates.ComposeServices find each other by service name.