Developers

A container cannot reach localhost on the Mac

Each container has its own network stack. In a container, localhost is the container itself, not the Mac.

Applies to: Docker Desktop and OrbStack on current macOS versions.Checked: 29 October 2026

Symptoms

An app in a container gets “connection refused” on localhost:5432 or a similar port.
The same URL works in Safari or Terminal on the Mac.
A model server or API on the Mac is not reachable from a dev container.

localhost points to the container. The container looks for the service in its own network stack, where nothing listens.
The host address changes. Docker's documentation says that the host IP address changes. It gives a special name for the host instead.
A firewall on the Mac. The macOS firewall or another firewall app can block incoming connections to the service.

Make sure that the service works on the Mac. Replace 8000 with your port.
```
curl http://localhost:8000
```
See which address the Mac service listens on.
```
lsof -nP -iTCP:8000 -sTCP:LISTEN
```
Output *:8000 means all addresses. 127.0.0.1:8000 means the loopback address only.
Test the host name from inside the container, if the image includes wget.
```
docker exec my-container wget -qO- http://host.docker.internal:8000
```

In the container, use host.docker.internal instead of localhost. Docker Desktop and OrbStack both support this name.
Set the address in the app's configuration, for example in an environment variable.
```
docker run -e API_URL=http://host.docker.internal:8000 my-image
```
With OrbStack, you can use host networking instead. Then Mac services are on localhost in the container.
```
docker run --net host my-image
```
If the connection still fails, look at the macOS firewall settings. See The macOS firewall blocks incoming connections.

Kilobat's checks run on the Mac, not in the container. Add --context container to get a command to run in the container.
```
kilobat why http://localhost:8000 --context container
```
If a hosted service calls your Mac, use --context provider. Kilobat then says that localhost is private and out of its reach.
```
kilobat why http://localhost:8000 --context provider
```

Does host.docker.internal work on Linux too?

This page covers the Mac. On Docker Desktop for Mac and OrbStack, the name resolves to the host.

Why does Safari reach the service when the container cannot?

Safari runs on the Mac, so localhost is the Mac. The container has its own localhost.

Sources checked on 29 October 2026. Man pages are the ones installed with macOS; open one with man <name> in Terminal.