Local DNS Mapping

Surge supports local DNS mapping. It is similar to /etc/hosts, but with more powerful features, including wildcards, aliases, and per-domain DNS server assignment.

[Host]
abc.com = 1.2.3.4
*.dev = 6.7.8.9
foo.com = bar.com
bar.com = server:8.8.8.8

Wildcard

You can use the * prefix to match subdomains. Surge uses simple string matching. For example, *google.com matches google.com, foo.google.com, and bargoogle.com. *.google.com does not match google.com.

[Host]
*.dev = 6.7.8.9

Alias

An alias works like a CNAME record.

[Host]
foo.com = bar.com

Assigning DNS Server

You can assign a specified DNS server to one or more domains.

[Host]
bar.com = server:8.8.8.8

Since Surge has its own DNS client implementation, some hostnames may fail to resolve. You can use 'server:system' to let the system handle the lookup.

[Host]
Macbook = server:system

server:syslib works similarly but keeps the query inside Surge while forwarding it to whatever DNS servers macOS is currently using. It is particularly useful in enhanced mode where the traditional system resolver might be bypassed.

server:force-syslib always uses the system library for resolution, even when enhanced mode is enabled. This is intended for special domains such as mDNS. Do not use it for general domains because it may cause recursive requests. Mac 6.4.3+

By default, all hostnames with the .local suffix are resolved by the system.

Referencing Rule Sets Mac 5.10.0+

When you already maintain large rule sets or domain sets, reproducing the same list in [Host] is tedious. Surge allows binding an entire DOMAIN-SET or RULE-SET to a DNS mapping entry so that the upstream or IP mapping is shared automatically.

[Host]
DOMAIN-SET:https://example.com/domains.txt = server:https://doh.example.com/dns-query
RULE-SET:https://example.com/rules.txt = 10.0.0.10

DOMAIN-SET: expects a domain list, while RULE-SET: can include mixed rule types (DOMAIN, DOMAIN-SUFFIX, IP ranges, etc.). This syntax follows the same remote file format described in Ruleset and is especially helpful for DOH/DOQ assignments that need to stay aligned with a managed list.

Use Local DNS Item Even For Proxies

[General]
use-local-host-item-for-proxy=true

By default, DNS resolution happens on the remote proxy server because Surge sends proxy requests with domains.

After enabling this option, for the requests that match a local DNS mapping record, Surge sends proxy requests with the local IP addresses instead of the original domains.

It only works for local DNS mapping records using an IP address.