Docksal runs a system service called
This service is responsible for the wildcard
*.docksal domain resolution to the Docksal IP (
It also forwards all other DNS requests to the upstream DNS server, which is Google’s Public DNS (
126.96.36.199) by default.
Project containers are configured to use
docksal-dns as their DNS server by default.
Docksal also configures network settings on Linux, Mac, and Windows to tell the host machine to use
docksal-dns as well.
On Mac, only
*.docksal DNS queries are routed through
On Linux and Windows DNS, all DNS queries are routed through
docksal-dns, as there is no way to configure this
selectively (like on Mac). In cases when the Docksal VM is stopped or the
docksal-dns service is down, the OS picks
the next available DNS server configured on the host (which would be your LAN/WiFi connection). This way, there is
always a fallback.
If you run into issues with DNS resolution, try disabling the automatic resolver:
fin system stop fin config set --global DOCKSAL_NO_DNS_RESOLVER=1 fin system start
You can then manually manage DNS records.
There are a few cases when you may have to manage DNS resolution manually:
In such cases, you will have to configure the host and container DNS resolution manually.
Host DNS resolution can be overridden using the OS
hosts file. Docksal provides a command to simplify the management
of this file - fin hosts.
To add a custom domain to the
hosts file, run:
fin hosts add local.example.com
To have your project containers resolve a custom DNS record, you can use the docker-compose extra_hosts parameter.
Add this parameter in the project’s
docksal.yml to any container, where you want your custom DNS records to work:
version: "2.1" services: cli: extra_hosts: - "www.example.com:127.0.0.1" - "example.com:127.0.0.1"
In the example above, we added two extra hosts to the
It is not possible to define wildcard DNS records using the manual approach (host and containers). You will have to add multiple individual records.
Some restricted network environments (e.g., corporate networks) may be blocking direct access to external DNS services,
188.8.131.52 inaccessible. In such cases, Docksal will output a warning on
fin project start with instructions
to override the default upstream DNS settings.
To override the upstream DNS server settings:
fin config set --global DOCKSAL_DNS_UPSTREAM=<dns-server-ip> fin system reset dns
Inspect your LAN or WiFi interface settings and connection status to figure out the DNS server your network is using.
# Enable logging DOCKSAL_DNS_DEBUG=true fin system reset dns # View logs fin docker logs docksal-dns