Desarrolladores

Un contenedor no puede acceder a localhost en el Mac

Cada contenedor tiene su propia pila de red. En un contenedor, localhost es el propio contenedor, no el Mac.

Se aplica a: Docker Desktop y OrbStack en las versiones actuales de macOS.Revisado: 29 de octubre de 2026

Síntomas

Una app en un contenedor recibe «connection refused» en localhost:5432 o en un puerto parecido.
La misma URL funciona en Safari o en Terminal en el Mac.
Un servidor de modelos o una API del Mac no es accesible desde un contenedor de desarrollo.

localhost apunta al contenedor. El contenedor busca el servicio en su propia pila de red, donde no escucha nada.
La dirección del host cambia. La documentación de Docker dice que la dirección IP del host cambia. En su lugar, ofrece un nombre especial para el host.
Un firewall en el Mac. El firewall de macOS u otra app de firewall puede bloquear las conexiones entrantes al servicio.

Comprueba que el servicio funciona en el Mac. Sustituye 8000 por tu puerto.
```
curl http://localhost:8000
```
Mira en qué dirección escucha el servicio del Mac.
```
lsof -nP -iTCP:8000 -sTCP:LISTEN
```
Salida *:8000 significa todas las direcciones. 127.0.0.1:8000 significa solo la dirección de loopback.
Prueba el nombre de host desde dentro del contenedor, si la imagen incluye wget.
```
docker exec my-container wget -qO- http://host.docker.internal:8000
```

En el contenedor, usa host.docker.internal en lugar de localhost. Docker Desktop y OrbStack admiten este nombre.
Indica la dirección en la configuración de la app, por ejemplo en una variable de entorno.
```
docker run -e API_URL=http://host.docker.internal:8000 my-image
```
Con OrbStack, también puedes usar la red del host. Así, los servicios del Mac están en localhost dentro del contenedor.
```
docker run --net host my-image
```
Si la conexión sigue fallando, revisa los ajustes del firewall de macOS. Consulta El firewall de macOS bloquea las conexiones entrantes.

Las comprobaciones de Kilobat se ejecutan en el Mac, no en el contenedor. Añade --context container para obtener un comando que ejecutar en el contenedor.
```
kilobat why http://localhost:8000 --context container
```
Si un servicio alojado llama a tu Mac, usa --context provider. Kilobat te dirá entonces que localhost es privado y queda fuera de su alcance.
```
kilobat why http://localhost:8000 --context provider
```

¿host.docker.internal funciona también en Linux?

Esta página trata del Mac. En Docker Desktop para Mac y en OrbStack, el nombre se resuelve al host.

¿Por qué Safari llega al servicio y el contenedor no?

Safari se ejecuta en el Mac, así que localhost es el Mac. El contenedor tiene su propio localhost.

Fuentes revisadas el 29 de octubre de 2026. Las páginas man son las que se instalan con macOS; abre una con man <name> en Terminal.