macOS: host.docker.internal reaches only the Mac's 127.0.0.1, not ::1, so localhost dev servers are unreachable

Open
#258 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
52/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
docker, node.js, python, rust

Research direction

The report identifies host.docker.internal, the Kiri relay, and loopback connections, but names no source files or tests. Start by locating the relay code that accepts these connections and how it chooses the Mac loopback address; reproduce the report with IPv6 and IPv4 loopback servers. Done means a container can reach a server listening only on ::1, with regression coverage for both address families.

Written by the indexing model from the issue text.

Description

Kiri version and system

  • Kiri 0.2.0, macOS 26.7.1, Apple silicon
  • Tailscale connected (the engine log notes that the VM's NAT network is unreachable and published
    ports go over vsock), in case it matters

What you did

A server on the Mac that listens only on IPv6 loopback, then the same server on IPv4 loopback,
fetched from a container through host.docker.internal:

mkdir -p /tmp/www && echo hello-from-mac > /tmp/www/ping.txt

cd /tmp/www && python3 -m http.server 3999 --bind ::1 &
docker --context kiri run --rm alpine wget -qO- -T4 http://host.docker.internal:3999/ping.txt
kill %1

cd /tmp/www && python3 -m http.server 3999 --bind 127.0.0.1 &
docker --context kiri run --rm alpine wget -qO- -T4 http://host.docker.internal:3999/ping.txt
kill %1

What happened

server on [::1]:        wget: error getting response: Invalid argument
server on [127.0.0.1]:  hello-from-mac

The TCP connection opens (Kiri's relay accepts it), then closes without data, so nc -z reports
the port open even when nothing behind it is reachable. host.docker.internal resolves to
198.19.248.254 and only ever reaches the Mac's 127.0.0.1.

This matters because Node binds localhost to ::1 on macOS (dns.lookup returns IPv6 first),
so Vite, AdonisJS and other Node dev servers that listen on localhost are unreachable from
containers. A reverse proxy container in front of a dev server on the Mac gets EOF from every
upstream. The same setup works on OrbStack.

The workaround is to make Node resolve localhost to IPv4 first, for example
NODE_OPTIONS=--dns-result-order=ipv4first, so the servers bind 127.0.0.1.

What you expected instead

What the docs describe in Networks and ports:
"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." For a Vite server on
localhost:5173, that loopback is ::1. The relay could try ::1 when 127.0.0.1 refuses, or
connect to localhost with both families the way a browser does.

Dominant language
Rust
Stars
7.5k
Forks
329
Avg merge
7h 48m
Merged PRs (30d)
105

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from libracoder/kiri

All issues in libracoder/kiri

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.