How to Connect From a Docker Container to a Host Service

Inside a Docker container, 127.0.0.1 and localhost refer to that container—not the Docker host. A container that tries to reach a database, proxy, or development server on the host through localhost will normally receive connection refused unless the service runs in the same container.

Confirm the client and destination

Inspect the application’s effective target without printing credentials:

docker inspect CONTAINER --format '{{json .Config.Env}}'
docker inspect CONTAINER --format '{{json .NetworkSettings.Networks}}'

Record the protocol, hostname, port, Docker network, and exact error. A refusal, timeout, DNS error, and TLS failure point to different layers.

Avoid copying full database URLs or environment output into shared logs because they may include passwords and tokens.

Understand the available host address

Docker Desktop commonly provides:

host.docker.internal

On Linux Engine, support depends on configuration. A portable Compose mapping for supported Docker versions is:

services:
  app:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Then test name resolution inside the container:

docker exec CONTAINER getent hosts host.docker.internal

Do not hard-code a bridge gateway such as 172.17.0.1 without confirming the network. User-defined networks can use different subnets and gateways.

Inspect the container gateway

docker inspect CONTAINER --format '{{range .NetworkSettings.Networks}}{{.Gateway}} {{end}}'
docker network inspect NETWORK

The gateway is often a host-side bridge address reachable from the container, but the service must listen on an address that accepts traffic arriving through that bridge.

Check the host listener

On the Docker host:

sudo ss -ltnp | grep ':PORT '

A service bound only to 127.0.0.1:PORT accepts host-local connections but not traffic addressed to the bridge interface. Configure the application to bind to the specific trusted host interface or an appropriate non-loopback address.

Binding to 0.0.0.0 can expose the service on every host interface. Review firewall policy and the environment before broadening the listener.

Test from the same network namespace

If the application image lacks diagnostic tools, use an approved temporary container on the same Docker network:

docker run --rm --network NETWORK curlimages/curl \
  -v http://host.docker.internal:PORT/

Only pull and run diagnostic images permitted by your supply-chain policy. Compare DNS resolution, TCP connection, and application response separately.

For TLS services, use the real hostname expected by the certificate instead of replacing it with an IP and accidentally creating a name mismatch.

Inspect firewall and forwarding policy

sudo nft list ruleset
sudo ufw status verbose
sudo firewall-cmd --list-all

Host firewalls may allow traffic from the LAN while rejecting Docker bridge subnets, or the reverse. Add only the narrow source subnet, destination address, port, and protocol required.

Do not disable the firewall or flush Docker-managed rules as a diagnostic shortcut.

Consider alternatives

If both workloads can run in Docker, placing them on the same user-defined network and connecting by service name is often clearer than routing through the host. For a production database or API, use its stable private DNS endpoint rather than coupling the container to a local bridge address.

network_mode: host changes isolation and portability and behaves differently across platforms. Use it only when its implications are understood, not as the default fix for one connection.

Diagnose it with Rumus

Diagnose why this Docker container cannot reach a service on its host. Identify the
effective destination without exposing credentials; inspect container networks,
DNS and gateway, host.docker.internal or host-gateway mapping, the host listener's
bind address, TCP reachability, firewall rules, platform differences, and TLS host
name requirements. Start read-only and do not recreate containers, broaden listener
addresses, disable firewalls, or use host networking without approval.

Confirm the fix

Test from the original application container and confirm the service receives the request:

docker exec CONTAINER getent hosts host.docker.internal
docker logs CONTAINER --since 10m

Verify the connection survives a container recreation, the hostname resolves to the intended host, and the service is not exposed to networks that should not reach it.