Troubleshoot container connections to host services

A container on a normal bridge network has its own loopback interface. To reach a host service, choose a host address reachable from that container, then verify the service listens on that address and port. Docker Desktop, native Linux, and rootless Engine do not all use the same path.

Choose a connection method

On Docker Desktop, use its built-in host name for an HTTP service:

curl --fail http://host.docker.internal:8080/

Run this inside a container containing curl. On Linux Engine 20.10 or later, an explicit mapping can provide the same name:

docker run --add-host host.docker.internal:host-gateway myapp:1.2

In Compose, put extra_hosts: ["host.docker.internal:host-gateway"] under the relevant service. The mapping resolves to the configured daemon-side host gateway; it does not open a port or bypass a firewall.

For a conventional native Linux bridge, inspect the host interface with ip addr show docker0, or inspect the relevant user-defined Docker network. Use the actual address rather than assuming 172.17.0.1. Desktop's bridge is inside its VM, while rootless networking can use a different gateway mechanism.

Consider host networking deliberately

docker run --network host myapp:1.2

On native Linux, this shares the host network namespace and makes its loopback services accessible. It also shares the host's port space, so conflicts and reduced network isolation must be considered. Docker Desktop 4.34+ has opt-in host networking for Linux containers with its own TCP/UDP limitations; it is no longer accurate to say host networking is categorically unavailable on Desktop.

Diagnose the actual failure

1. Resolve the name from the client container, for example with getent hosts host.docker.internal where that tool exists. A missing mapping is one possible cause, not the only DNS problem.
2. On a Linux host, inspect the listener with ss -ltnp 'sport = :8080'. A native bridge client cannot reach a service through a bridge address when the service only binds to loopback. Bind the intended interface rather than automatically widening to all interfaces.
3. Check the relevant host firewall, route, and Docker network policy. Use tooling appropriate to the actual iptables/nftables/firewalld setup; do not disable filtering to test blindly.
4. Test the service's real protocol and authentication. Successful name resolution or ICMP says little about an HTTP response or database login.

FAQ

Can I mount a Unix socket instead?

For a daemon-local Linux setup, a deliberate bind mount can expose a compatible application socket. Verify numeric permissions and the server's socket lifecycle. The path belongs to the Docker daemon host, and Desktop file sharing does not make every Unix socket portable. A Docker daemon socket also carries much broader authority than a database socket.

What changes in Swarm or Kubernetes?

The task may run on another node, so a host-local dependency needs explicit placement and routing. Kubernetes status.hostIP can identify the Pod's node. hostPort publishes a Pod port and does not itself provide access to an unrelated node service. A stable service endpoint often reduces this coupling.

See Desktop networking and host networking.