Accessing the Host Machine from Inside a Docker Container Across Linux, macOS & CI/CD

When running ephemeral AI agent sandboxes, local microservice integration tests, or reverse proxies inside Docker, a container frequently needs to connect to a service listening on the host machine (such as a local PostgreSQL instance, an MCP SSE bridge, or a mock webhook server).

1. Cross-Platform Host Resolution with `host-gateway`

While Docker Desktop on macOS and Windows automatically resolves host.docker.internal, native Linux Docker Engine requires explicitly mapping the special host-gateway token via --add-host or Docker Compose extra_hosts:

# docker-compose.yml
services:
  agent-sandbox:
    image: my-agent-sandbox:latest
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      - MCP_SSE_URL=http://host.docker.internal:8910/sse

2. Linux Firewall (`ufw` / `iptables`) Considerations

Remember that traffic from a bridge container arrives on the docker0 interface (typically 172.17.0.0/16). Ensure your host service binds to 0.0.0.0 or the docker0 gateway IP rather than 127.0.0.1, and allow the Docker bridge subnet through ufw for the target port.