Unable to Access Local Service on macOS Docker Host

Last updated: October 15, 2026

Applicable to:

  • Twingate Component: Connector

  • Platform: Docker for macOS

Overview

When the Twingate Connector runs as a container in Docker Desktop for Mac, it can’t reach a service running on the Mac itself using localhost, 127.0.0.1, or --network host.

Docker Desktop provides a special address that routes from the container back to the Mac. Point your Twingate Resource at that address and the Connector can reach services on the host.

Prerequisites

  • A macOS host with Docker Desktop for Mac installed

  • A Twingate Connector deployed on that host using Docker

Process

Option 1: Use host.docker.internal (no extra arguments needed)

Docker Desktop automatically resolves host.docker.internal to the Mac host in every container.

  1. In the Twingate Admin Console, add host.docker.internal as a Resource on the Remote Network where the Connector is deployed.

  2. Connect to the Resource from a Twingate Client using host.docker.internal and the service’s port.

Option 2: Use a custom hostname with --add-host

If you’d prefer a hostname of your own, map it to the host when you start the Connector container.

  1. Add the following argument to your Connector’s docker run command, replacing <hostname.internal> with a hostname of your choosing:

    --add-host <hostname.internal>:host-gateway

    A full example looks like this, where values in <> are specific to your deployment:

    docker run -d \
  --sysctl net.ipv4.ping_group_range="0 2147483647" \
  --env TWINGATE_NETWORK="<network-name>" \
  --env TWINGATE_ACCESS_TOKEN="<access-token>" \
  --env TWINGATE_REFRESH_TOKEN="<refresh-token>" \
  --env TWINGATE_LABEL_HOSTNAME="$(hostname)" \
  --env TWINGATE_LABEL_DEPLOYED_BY="docker" \
  --add-host <hostname.internal>:host-gateway \
  --name "twingate-connector" \
  --restart=unless-stopped \
  --pull=always \
  twingate/connector:1

    If the Connector is already running, remove it and run the command again with the new argument. Arguments can’t be added to an existing container.

  2. In the Twingate Admin Console, add <hostname.internal> as a Resource on the Remote Network where the Connector is deployed.

 Related