Entwickler

Ein Container erreicht localhost auf dem Mac nicht

Jeder Container hat seinen eigenen Netzwerk-Stack. Im Container ist localhost der Container selbst, nicht der Mac.

Gilt für: Docker Desktop und OrbStack unter aktuellen macOS-Versionen.Geprüft: 29. Oktober 2026

Symptome

  • Eine App im Container erhält „connection refused“ auf localhost:5432 oder einem ähnlichen Port.
  • Dieselbe URL funktioniert in Safari oder im Terminal auf dem Mac.
  • Ein Modellserver oder eine API auf dem Mac ist aus einem Dev-Container nicht erreichbar.

Mögliche Ursachen

  • localhost zeigt auf den Container. Der Container sucht den Dienst in seinem eigenen Netzwerk-Stack, wo nichts lauscht.
  • Die Host-Adresse ändert sich. Laut Docker-Dokumentation ändert sich die IP-Adresse des Hosts. Stattdessen gibt es einen speziellen Namen für den Host.
  • Eine Firewall auf dem Mac. Die macOS-Firewall oder eine andere Firewall-App kann eingehende Verbindungen zum Dienst blockieren.

So prüfst du es

  1. Prüfe, ob der Dienst auf dem Mac funktioniert. Ersetze 8000 durch deinen Port.

    curl http://localhost:8000

  2. Sieh nach, auf welcher Adresse der Dienst auf dem Mac lauscht.

    lsof -nP -iTCP:8000 -sTCP:LISTEN

    Ausgabe *:8000 steht für alle Adressen. 127.0.0.1:8000 steht nur für die Loopback-Adresse.

  3. Teste den Hostnamen im Container, falls das Image wget enthält.

    docker exec my-container wget -qO- http://host.docker.internal:8000

So behebst du es

  1. Verwende im Container host.docker.internal statt localhost. Docker Desktop und OrbStack unterstützen beide diesen Namen.

  2. Trage die Adresse in die Konfiguration der App ein, zum Beispiel in einer Umgebungsvariable.

    docker run -e API_URL=http://host.docker.internal:8000 my-image

  3. Mit OrbStack kannst du stattdessen das Host-Netzwerk verwenden. Dann erreichst du die Dienste des Mac im Container unter localhost.

    docker run --net host my-image

  4. Wenn die Verbindung weiterhin fehlschlägt, prüfe die Firewall-Einstellungen von macOS. Siehe Die macOS-Firewall blockiert eingehende Verbindungen.

Mit Kilobat

  1. Kilobats Prüfungen laufen auf dem Mac, nicht im Container. Füge --context container hinzu, um einen Befehl für den Container zu erhalten.

    kilobat why http://localhost:8000 --context container

  2. Wenn ein gehosteter Dienst deinen Mac aufruft, verwende --context provider. Kilobat meldet dann, dass localhost privat und von dort nicht erreichbar ist.

    kilobat why http://localhost:8000 --context provider

Fragen

Funktioniert host.docker.internal auch unter Linux?

Diese Seite behandelt den Mac. Unter Docker Desktop für Mac und OrbStack wird der Name zum Host aufgelöst.

Warum erreicht Safari den Dienst, der Container aber nicht?

Safari läuft auf dem Mac, also ist localhost dort der Mac. Der Container hat sein eigenes localhost.

Quellen

Quellen geprüft am 29. Oktober 2026. Die Manpages sind die mit macOS installierten; öffne eine mit man <name> im Terminal.