Como funcionam as redes de contêineres no Mac
O macOS não executa contêineres Linux diretamente, então todo app de contêineres no Mac os executa em um ambiente Linux e retransmite o tráfego entre ele e o Mac. Três caminhos importam:
- Entrada: uma porta publicada no Mac encaminha para um contêiner.
- Saída: um contêiner abre uma conexão com a internet, a rede da empresa ou um serviço no Mac.
- Nomes: um contêiner resolve um nome de host.
Quando esses caminhos contornam a rede do próprio Mac, as rotas de VPN não se aplicam, nomes de host internos não resolvem e o firewall não identifica qual app está se comunicando. O Oxcart foi projetado para evitar isso.
Saída: sua VPN, seu DNS e seu firewall continuam valendo
O Oxcart redireciona o TCP de saída dos contêineres e das etapas de build, IPv4 e IPv6, para o Mac, que abre a conexão com seus próprios sockets. A tabela de rotas do Mac decide o destino, incluindo as rotas instaladas pelo cliente VPN. O Oxcart não altera rotas do Mac, configurações de VPN nem preferências de firewall.
Consultas de endereço (A e AAAA) usam o resolvedor do macOS, incluindo /etc/hosts e a seleção de resolvedores configurada pela VPN, então nomes da empresa resolvem nos contêineres como no navegador. Os nomes de contêineres continuam restritos às suas redes Docker, e o DNS funciona por UDP e TCP.
Little Snitch, LuLu e agentes de endpoint
Um filtro de rede costuma segurar a primeira conexão de um programa novo por cerca de dois segundos enquanto pede sua autorização. O Oxcart não espera: as conexões usam um caminho alternativo até o principal ser validado; uma conexão lenta ou com falha migra sozinha para a alternativa; e três falhas seguidas suspendem o caminho principal por 30 segundos antes de uma nova verificação. Aprove o Oxcart uma vez no filtro e suas regras passam a valer daí em diante.
Entrada: portas publicadas
Publique portas com a sintaxe normal do Docker:
# Mac loopback only (recommended for development)
docker run -d -p 127.0.0.1:8080:80 nginx
# Ephemeral host port, UDP
docker run -d -p 127.0.0.1::9000/udp my-udp-service
# IPv4 and IPv6 listeners on the Mac
docker run -d -p "[::]:8080:80" nginxUm vínculo sem endereço escuta em todos os endereços IPv4 do Mac, tornando-o acessível a outras máquinas da rede, a menos que o firewall do macOS as bloqueie. TCP e UDP podem usar o mesmo número de porta do host. As portas de escuta publicadas são liberadas quando o contêiner para.
Portas publicadas também respondem no localhost do próprio mecanismo, então um registro executado em um contêiner funciona como destino de push:
docker run -d -p 127.0.0.1:5000:5000 --name registry registry:2
docker tag my-app localhost:5000/my-app
docker push localhost:5000/my-appA visualização Ports: por que uma porta não responde
A visualização Ports do Oxcart lista todas as portas de escuta do Mac e dos contêineres, agrupadas por repositório, worktree e branch, para que duas cópias do mesmo projeto não se confundam. Cada vínculo fica pronto, pendente ou com erro, com o motivo:
- o endereço já está em uso no Mac;
- o servidor no contêiner só escuta em
127.0.0.1; - ainda não há nada escutando nessa porta.
Portas acessíveis a outras máquinas recebem uma marcação. Seu agente de programação vê as mesmas informações pela ferramenta MCP ports do Oxcart; consulte Docker para agentes de programação com IA.
Acessando o Mac a partir de um contêiner
host.docker.internal resolve em contêineres e etapas de build e alcança serviços vinculados ao 127.0.0.1 do Mac por TCP. Aponte um contêiner para um banco ou servidor de desenvolvimento rodando nativamente no Mac:
docker run --rm curlimages/curl http://host.docker.internal:3000/healthTrate isso como uma abertura deliberada: qualquer contêiner executado pode acessar serviços no loopback do Mac dessa forma, então não deixe serviços administrativos sem autenticação em 127.0.0.1 enquanto executa contêineres em que não confia.
A conexão criptografada entre o Mac e o mecanismo
O tráfego entre o Mac e o ambiente Linux atravessa uma rede virtual que o macOS compartilha com outros softwares de virtualização no mesmo Mac. O Oxcart transporta o TCP publicado e de saída nessa conexão dentro de TLS 1.3 (TLS_AES_128_GCM_SHA256), com pinning de um certificado novo a cada inicialização do mecanismo e um token bearer de 256 bits por inicialização. Um token inválido encerra a conexão, e o lado Linux fecha conexões que não vêm do endereço do Mac antes de iniciar o TLS.
A ameaça tratada aqui: outros softwares nessa rede compartilhada falsificando endereços para ler ou injetar tráfego, ou abrir novas conexões com seus contêineres. Um firewall no ambiente convidado também impede que esses softwares acessem portas de contêineres não publicadas e o resolvedor interno. A criptografia tem um custo nessa conexão, e escolhemos assumi-lo. A API Docker nunca passa pela rede: usa um socket Unix privado e, sem portas publicadas, o Oxcart não mantém nenhum socket TCP ou UDP no Mac.
Limitações atuais
- O modo de rede do host (
--network host) e redes IPv6 de contêineres não estão implementados; os contêineres têm endereços IPv4. host.docker.internaltransporta TCP; UDP para o gateway do host não está implementado.- TCP e UDP publicados não preservam o endereço do cliente: o contêiner vê o lado Linux como o par da conexão.
- Registros DNS que não são de endereço (como SRV e TXT) usam os resolvedores DHCP da rede, não o DNS dividido do macOS.
Solução de problemas
| Sintoma | Causa provável | Solução |
|---|---|---|
Conexão recusada em localhost:PORT | O servidor escuta em 127.0.0.1 dentro do contêiner | Escute em 0.0.0.0; a visualização Ports identifica esse caso |
| "port is already allocated" | Outro processo ou contêiner está usando a porta do host | Escolha outra porta do host; a visualização Ports mostra quem a usa |
| Nome de host interno não resolve no contêiner | O nome só existe no DNS da VPN | Conecte a VPN no Mac; consultas de endereço seguem o resolvedor do Mac |
| O contêiner não alcança um servidor de desenvolvimento no Mac | Uso de localhost dentro do contêiner | Use host.docker.internal |
| O primeiro download trava por alguns segundos | Um filtro de rede está pedindo autorização para uma nova conexão | Aprove o Oxcart uma vez; enquanto isso, as conexões usam o caminho alternativo |
| Colegas conseguem acessar sua porta de desenvolvimento | Publicada sem endereço | Publique em 127.0.0.1 |
Perguntas
Contêineres Docker no Mac usam minha VPN?
No Oxcart, sim. Conexões de saída dos contêineres são abertas pelo próprio Mac, então as rotas, a VPN, o DNS dividido para consultas de endereço e o firewall por app do Mac se aplicam a elas. O Oxcart não altera rotas do Mac, configurações de VPN nem preferências de firewall.
Como acesso um serviço no Mac a partir de um contêiner?
Use host.docker.internal. No Oxcart, ele alcança serviços vinculados ao 127.0.0.1 do Mac por TCP, de contêineres e de etapas de build. --add-host mac:host-gateway fornece outro nome para o mesmo endereço.
Por que vejo o contêiner rodando, mas não consigo acessar sua porta?
Geralmente o servidor dentro do contêiner escuta em 127.0.0.1, que portas publicadas não alcançam; faça-o escutar em 0.0.0.0. Outras causas são uma porta do host já em uso ou nada escutando ainda. A visualização Ports do Oxcart mostra qual é o caso.
O Oxcart funciona com Little Snitch e LuLu?
Sim. Quando um filtro de rede segura a primeira conexão do Oxcart enquanto pede sua autorização, as conexões seguem um caminho alternativo até o principal ser validado, sem interromper nada nem esperar sua resposta. Uma conexão lenta ou com falha migra sozinha para a alternativa.
O tráfego dos contêineres é criptografado no Mac?
O TCP publicado e de saída entre o Mac e o mecanismo do Oxcart trafega dentro de TLS 1.3, com pinning de um certificado criado a cada inicialização do mecanismo e um token de 256 bits por inicialização. Isso protege a conexão de outros softwares de virtualização na rede compartilhada do Mac. O tráfego para a internet é protegido pelo que o próprio app usa, como HTTPS.
Minhas portas publicadas ficam visíveis para outras máquinas na rede?
Uma porta publicada sem endereço escuta em todos os endereços IPv4 do Mac, então outras máquinas podem acessá-la, a menos que o firewall do macOS as bloqueie. Publique em 127.0.0.1 para restringir ao Mac. O Oxcart marca portas acessíveis a outras máquinas.
O Oxcart oferece rede do host ou IPv6 para contêineres?
Não. O modo de rede do host e redes IPv6 de contêineres não estão implementados. Os contêineres têm endereços IPv4; as portas ainda podem ser publicadas em IPv6 com "[::]:8080:80".
Fontes e método
O comportamento de rede descrito aqui foi testado no Oxcart em 10 de outubro de 2026, incluindo TCP de saída, DNS, portas publicadas, acesso ao host e TLS na conexão entre o Mac e os contêineres.