---
title: "Acessar um serviço localhost do Mac a partir de um contêiner Docker · Guias do Kilobat"
url: "https://kilobat.app/pt/guides/localhost-from-container"
description: "Dentro de um contêiner, localhost é o próprio contêiner. Use host.docker.internal para acessar um banco de dados, API ou servidor de modelos em execução no Mac."
---

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.

## Possíveis causas

- **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.

## Como verificar

1. Verifique se o serviço funciona no Mac. Substitua 8000 pela sua porta.

   ```
   curl http://localhost:8000
   ```
2. 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.
3. 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
   ```

## Como corrigir

1. No contêiner, use `host.docker.internal` em vez de `localhost`. Docker Desktop e OrbStack aceitam esse nome.
2. 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
   ```
3. 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
   ```
4. Se a conexão ainda falhar, confira os ajustes do firewall do macOS. Consulte [O firewall do macOS bloqueia conexões recebidas](https://kilobat.app/pt/guides/macos-firewall-incoming).

## Com o Kilobat

1. 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
   ```
2. 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
   ```

## Perguntas

**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.

## Fontes

- [Documentação do Docker: Explore instruções de rede no Docker Desktop](https://docs.docker.com/desktop/features/networking/networking-how-tos/)
- [Documentação do OrbStack: Rede de contêineres](https://docs.orbstack.dev/docker/network)
- [OrbStack Docs: Host networking](https://docs.orbstack.dev/docker/host-networking)
- lsof(8), página de manual instalada com o macOS 27.2

Verificado em 29 de outubro de 2026.

## Guias relacionados

- [Não é possível acessar um contêiner Docker a partir do Mac](https://kilobat.app/pt/guides/docker-container-from-mac): O Docker no Mac executa contêineres em uma máquina virtual Linux.
- [O firewall do macOS bloqueia conexões de entrada](https://kilobat.app/pt/guides/macos-firewall-incoming): O firewall do macOS controla conexões iniciadas por outros computadores com seu Mac.
- [Descubra por que um site ou API não conecta](https://kilobat.app/pt/guides/recipes/why-cant-it-connect): Quando a internet funciona, mas um endereço falha, o Kilobat verifica cada camada por vez.
- [Porta já está em uso no Mac](https://kilobat.app/pt/guides/port-already-in-use): Só um processo pode escutar em uma porta TCP e endereço.