Desenvolvedores

Um contêiner não consegue acessar localhost no Mac

Cada contêiner tem sua própria pilha de rede. Em um contêiner, localhost é o próprio contêiner, não o Mac.

Aplica-se ao Docker Desktop e OrbStack nas versões atuais do macOS.Verificado: 29 de outubro de 2026

Sintomas

Um app em um contêiner recebe “connection refused” em localhost:5432 ou em uma porta semelhante.
A mesma URL funciona no Safari ou no Terminal do Mac.
Um servidor de modelos ou API no Mac não pode ser acessado por um contêiner de desenvolvimento.

localhost aponta para o contêiner. O contêiner procura o serviço na própria pilha de rede, onde não há nada aguardando conexões.
O endereço do host muda. A documentação do Docker informa que o IP do host muda e fornece um nome especial para o host.
Um firewall no Mac. O firewall do macOS ou outro app de firewall pode bloquear conexões recebidas pelo serviço.

Verifique se o serviço funciona no Mac. Substitua 8000 pela sua porta.
```
curl http://localhost:8000
```
Veja em qual endereço o serviço do Mac aguarda conexões.
```
lsof -nP -iTCP:8000 -sTCP:LISTEN
```
Saída *:8000 indica todos os endereços. 127.0.0.1:8000 indica apenas o endereço de loopback.
Teste o nome do host dentro do contêiner, se a imagem incluir wget.
```
docker exec my-container wget -qO- http://host.docker.internal:8000
```

No contêiner, use host.docker.internal em vez de localhost. Docker Desktop e OrbStack aceitam esse nome.
Defina o endereço na configuração do app, por exemplo em uma variável de ambiente.
```
docker run -e API_URL=http://host.docker.internal:8000 my-image
```
Com o OrbStack, você também pode usar a rede do host. Assim, os serviços do Mac ficam em localhost no contêiner.
```
docker run --net host my-image
```
Se a conexão ainda falhar, confira os ajustes do firewall do macOS. Consulte O firewall do macOS bloqueia conexões recebidas.

As verificações do Kilobat são executadas no Mac, não no contêiner. Adicione --context container para obter um comando a executar no contêiner.
```
kilobat why http://localhost:8000 --context container
```
Se um serviço hospedado chamar seu Mac, use --context provider. O Kilobat informará que localhost é privado e está fora do seu alcance.
```
kilobat why http://localhost:8000 --context provider
```

O host.docker.internal funciona no Linux também?

Esta página trata do Mac. No Docker Desktop para Mac e no OrbStack, o nome resolve para o host.

Por que o Safari acessa o serviço quando o contêiner não consegue?

O Safari é executado no Mac, então localhost é o Mac. O contêiner tem seu próprio localhost.

Verificado em 29 de outubro de 2026.