Alias DNS to host.docker.internal in Docker: Complete Guide (2026)

In this tutorial, we will explore how to alias a DNS name to host.docker.internal inside a Docker container. This is particularly useful when you have a service running on your host machine that you want to access securely from within a Docker container using a custom domain name and a valid SSL certificate.

Key Takeaways

• Learn how to map a DNS name to host.docker.internal inside Docker.
• Understand the importance of resolving host services securely in development.
• Implement solutions that work on macOS and other operating systems.
• Troubleshoot common connectivity issues within Docker containers.

When developing applications locally, it's common to run services on your host machine and access them from within a Docker container. However, accessing these services securely using a domain name and SSL can be challenging. This is where aliasing a DNS name to host.docker.internal becomes invaluable. This tutorial will guide you through the steps needed to achieve this setup, ensuring secure communication between your Docker container and host services.

Prerequisites

• Basic understanding of Docker and containerization
• A local development environment with Docker installed (version 24.0.0 or later)
• Access to a service running on your host machine with SSL configured
• macOS environment (though similar principles apply to other OSes)

Step 1: Configure Your Host Service

Ensure that your service is running on your host machine and is accessible via a custom domain with SSL. For instance, you have a service running at https://dev.mycoolproject.com:8443 with an SSL certificate.

Verify that your service is reachable from the host machine using the domain name:

curl -v https://dev.mycoolproject.com:8443

Ensure that this command returns a successful connection with the expected certificate.

Step 2: Map DNS Name to host.docker.internal

Docker provides a special DNS name host.docker.internal to access the host machine. However, to use your custom domain, you need to alias this DNS name inside your Docker container. This can be done by editing the /etc/hosts file inside the container.

docker run --rm -d --name my_container \
  --add-host=dev.mycoolproject.com:host.docker.internal \
  my_image

This command runs a Docker container with an additional host entry mapping the domain dev.mycoolproject.com to host.docker.internal.

Step 3: Verify the DNS Alias Inside the Container

To ensure the alias is set up correctly, you can use the ping command or similar network tools inside the running container:

docker exec -it my_container ping dev.mycoolproject.com

The output should show that dev.mycoolproject.com resolves to the IP address of host.docker.internal.

Step 4: Test Secure Connection from the Container

Now, test the secure connection from your client application inside the Docker container:

curl -v https://dev.mycoolproject.com:8443

This should successfully connect to your host service using the SSL certificate associated with dev.mycoolproject.com.

Common Errors/Troubleshooting

• Connection Refused: Ensure the service is running and accessible on the host machine.
• SSL Certificate Issues: Verify that the SSL certificate is valid and matches the domain name.
• DNS Resolution Failure: Double-check the --add-host parameter for typos and correctness.

If you encounter any errors, double-check the configurations and ensure that your Docker version supports host.docker.internal (Docker Desktop for Mac/Windows).

By following these steps, you should be able to access host services securely from within your Docker container using a custom domain name.

Frequently Asked Questions

What is host.docker.internal?

It is a special DNS name provided by Docker to allow containers to access the host machine.

Why can't I access my host service from Docker?

Ensure the service is running and correctly configured to accept connections from Docker containers.

Can I use this setup on Windows?

Yes, Docker Desktop for Windows also supports host.docker.internal.