Surge Mac

Version 4.1.0


你现在可以通过 UI 界面配置脚本了。




  1. 添加了关于配置文件的 HTTP API,包括 GET /profiles 和 POST /profiles/check。

  2. 添加了关于设备管理的 HTTP API,包括 GET /devices、POST /devices 和 GET /devices/icon。

  3. HTTP API、代理服务、外部控制器(external controller)现在都支持监听 IPv6 地址了(UI 界面尚无,需要手动在配置文件里配置)。

  4. 你可以用 http-api-tls=true 来为 HTTP API 启用 TLS(HTTPS-API)。


外部资源在 Surge 启动时就会更新,并且当应用一个配置文件时会自动下载其中引用的外部资源。


  1. 新的规则类型:SUBNET,可以用通配符匹配 SSID、BSSID 和 路由IP地址。

  2. 当处理大量请求的时候,Dashboard 性能有显著提升。


Version 4.0.5

Policy Group

In this release, we completely refactored the policy group functionality, bringing the following changes:

  1. The url-test/fallback/load-balance policy group can no longer be configured with a specific testing URL but with a global testing URL or a policy-configured testing URL. The policy's test results can be used directly in all policy group decisions, eliminating the need to retest each policy group individually.

  2. All types of policy groups support mixed nesting. The only requirement is that no circular references can be used.

  3. When a group policy is used as a sub-policy of the url-test/fallback/load-balance group.

    • The latency of the select/url-test/fallback/ssid group is the latency of the selected policy.

    • The latency of the load-balance group is the average of the latencies of all available policies.

  4. The timeout parameter of a policy group marks policies with latency exceeding this parameter as unavailable when making decisions for the group. But the maximum time taken to test the policy group is controlled by the global test-timeout parameter. (Default is 5s)

  5. When testing a group due to decision making, all sub-policies that the group may use are tested, including sub-policies of the sub-policy group.

  6. You may use no-alert=true parameter to suppress notifications for particular groups.

Cloud Notification

You can receive the notifications on iOS devices. Enable this option first and then configure it on Surge iOS. The two device must use a same iCloud account.

Minor Changes

  • Bug fixes.

Version 4.0.4

  • Bug fixes.

Version 4.0.3

  • You may override the testing URL of a policy for network diagnostics and activity cards.

  • The GeoIP database can be updated automatically in the background.

  • Bug fixes.

Version 4.0.2

  • You may now customize the GeoIP database updating URL.

  • tun-excluded-routes and tun-included-routes are now available for Surge Mac.

  • Bug fixes.

Version 4.0.1

  • You may configure the proxy chain with the UI now.

  • Fixed some visual inconsistency under reducing transparency mode.

  • Bug fixes.

Version 4.0.0

  • The first version of 4.0.0.

Surge Mac V3

Version 3.5.8

  • Bug fixes

Version 3.5.7

  • Bug fixes

Version 3.5.5

Minor Changes

  • All URL resources now support URLs with a username and password (e.g., including managed profile, external resources, and importing profile form URL.

  • You may switch among the main views with shortcut keys.

  • Bug fixes.

Version 3.5.4

Changes in Policy Group

  • New parameter: policy-regex-filter. If the parameter is configured, only matched policy line will be used.

Minor Changes

  • Provides more details for the TLS handshake error.

  • Increases the file description limitation alert threshold.

Version 3.5.3

New Parameter: use-local-host-item-for-proxy


use-local-host-item-for-proxy = true

If use-local-host-item-for-proxy is true, Surge sends the proxy request with the IP address defined in the [Host] section, instead of the original domain.

Changes in Load Balance Group

  • load-balance group now supports connectivity testing before being used. Add 'url' parameter to enable it.

  • Parameters 'timeout', 'interval' and 'evaluate-before-use' are also available.

Minor Changes

  • Surge will send an ICMP port unreachable message if UDP forwarding fails.

  • Eliminate unnecessary local DNS lookup while forwarding UDP traffic to a proxy server.

  • Fixed a bug that connecting to Surge iOS via USB is not working in Surge Dashboard.

Version 3.5.2

SSID Suspend

  • Surge Mac supports SSID suspend now. The system proxy and enhanced mode will be temporarily suspended under specified SSIDs.

  • The name of WiFi can be an SSID, a BSSID, or a gateway IP address.

  • No UI configuration in the current version.


  • REJECT-DROP policy is now effective to proxy connections. The connections matched with a REJECT-DROP policy will be closed in 60-120s later without any data returned.

Global Proxy

  • You may now select and view sub-policy for policy groups while using the global proxy mode.

Version 3.5.1

New rule type: DOMAIN-SET

  • DOMAIN-SET is just like RULE-SET. But it is designed a large number of rules and highly efficient.

  • Unlike RULE-SET, you can only write hostnames (domain or IP address) in it. One hostname per line.

  • You may use "." prefix to include all sub-domains.

Changes in SRC-IP

  • SRC-IP rule now supports IP-CIDR for both IPv4 and IPv6.

Changes in DNS over HTTPS

  • From this version, if DNS-over-HTTPS is configured, the traditional DNS will only be used to test the connectivity and resolve the domain in the DOH URL.

  • The DNS over HTTPS now has a separate parameter: doh-server. The DOH servers in 'dns-server' will be moved to the new parameter after saving.

  • The legacy DNS is always required now.

  • DOH can be matched with rule 'PROTOCOL,DOH' now.

  • Added a new parameter 'doh-follow-outbound-mode'. In the previous version, the DOH client follows the system proxy settings. From this version, all DOH requests will use DIRECT policy by default. If 'doh-follow-outbound-mode' is set, the DOH requests will follow the outbound mode settings regardless of the system proxy settings.

  • We are refactoring the HTTP client for DOH and scripting. Please feedback if you encounter any issue.

Changes in Scripting

  • Added a simple view to test the script. You may find it in the Window menu.

Minor Changes

  • Fixed a crash in Dashboard while using search.

  • Bug fixes.

Known Issues

  • You may not configure DOH with UI in this version temporarily.

Version 3.5.0

  • New feature: Module, which can override the current profile with a set of settings. Highly flexible for diverse purposes. See the post in the community for more information:

  • You may enable modules in the menu now.

  • You may view the detail of a module by double clicking.

  • Supports pattern filter for Dashboard requests.

  • Added a new rule type: PROTOCOL. The possible values are HTTP, HTTPS, SOCKS, SNELL, TCP, UDP.

  • You may now use UI to add and edit load-balance group.

    • DNS over HTTP (DoH) now uses DNS wireformat by default. You may configure doh-format=json in [General] to continue using JSON format.

    • TCP connection setup optimizations.

    • Bug fixes.

Version 3.4.0

  • Snell protocol now upgrade to version 2, supporting to reuse TCP connections to improve performance.

  • Supports a new proxy protocol: Trojan.

  • Remote Dashboard now upgraded to Remote Controller. You may use Surge iOS to select policy group, toggle HTTP capture/MitM, and switch outbound mode remotely.

  • The comment lines in the text config won't lost after editing with UI.

  • You may open the new connection window of Dashboard by holding the Option key while clicking the Dashboard item in the main menu.

  • Supports to use OpenSSL as TLS provider. See the post in the community for more information:

  • Fixed a bug that Surge may not be able to process DNS answer packets which is longer than 512 bytes.

Version 3.3.3

  • Fixed a bug which causes TFO failed.

  • You may use a profile which stores in a subdirectory of the profile directory.

  • Added Traditional Chinese localizations.

  • Fixed a bug that the menu might be unresponsive.

  • Fixed crashs on macOS 10.11.

Version 3.3.2

  • Supports MITM on non-standard port for TCP mode.

  • Proxy editing view now supports VMess protocol and all misc options.

  • A new option 'persistent' has been added to the load-balance group. (aka PCC, per connection classifier) When 'persistent=true' is set, a same hostname will always get the same policy.

  • Bug fixes.

Version 3.3.1

  • Supports VMess proxy protocol.

    • vmess-proxy= vmess,, 443, username = 12345678-abcd-1234-1234-47ffca0ce229, ws=true, tls=true, ws-path=/v2, ws-headers=X-Header-1:value|X-Header-2:value

    • All proxy options for TLS proxy are available.

    • Web-socket and TLS options would degrade performance. Only enable when necessary.

    • Surge only supports chacha20-poly1305 encryption algorithm. Please make sure the server supports it. We have no plan to implement other ciphers.

Version 3.3.0

  • The scripting has been rewritten totally. The old scripts are not compatible with this version. See

  • Added support for TLS 1.3. Append 'tls13=true' to the proxy line to enable it. (Requires macOS 10.14 or above)

  • Supports to use 'X-Surge-Policy' to force policy for HTTP/HTTPS requests.

  • SSID group now supports to use the IP address of default router as an identifier.

  • New policy group type: load-balance, which will use a random sub-policy for every request.

  • Supports DNS over HTTPS. More information in community:

  • IN-PORT and DEST-PORT rule now supports port range expression: DEST-PORT,8000-8999,DIRECT

  • Provides compatibility for Surge iOS 4.

  • Surge Mac software package is now notarized by Apple.

  • A new standalone view to manage all external resources.

Version 3.2.1

  • Fixed a bug that Handoff doesn't work between Surge iOS and Dashboard.

  • Fixed a bug that 'Update All Remote Resources' may not work.

Version 3.2.0



  • USB module has been refactored to improve stability. Also, you may choose the device from multiple USB devices now.


  • HTTP and MitM engine has been refactored. Please report if you encounter any issues.

  • You can now use URL-REGEX rule for MitM connections.

  • You may use prefix '-' to exclude domains for MitM. Example:

      hostname = -*, -*, *
  • MitM hostname list now supports port number. By default only the connections to port 443 will be decrypted. Use suffix :port to enable MitM for other ports. Use suffix :0 to enable MitM for all ports on the hostname.

  • URL rewrite type 'header' is now available for MitM connections. You may also use it to rewrite a plain HTTP request to an HTTPS request.


  • You can now enable/disable a rule.

  • Added a small indicator in the menu icon for Metered Network Mode.</lo>

  • Added main switches for rewrite and scripting.

  • Supports TCP SACKs for Surge VIF.

  • New general option: force-http-engine-hosts. You can force Surge to treat a raw TCP connection as an HTTP connection, to enable high-level functions such as URL-REGEX rules, rewrite and scripting. This option uses the same format as [MITM] hostname option.

  • New option for url-test/fallback group: evaluate-before-use. By default, the requests before a connection evaluation will use the first policy in the list and trigger the evaluate. Enable the option to delay the requests until the evaluation completed.

Version 3.1.1

  • Bug fixes.

Version 3.1.0

  • Added more feature to the main menu.

  • Dashboard now supports to export all requests to an archive file for opening later or sharing.

  • Supports a new proxy protocol: Snell. (

  • Surge Mac can work as a Snell proxy server now. See for more information.

  • A new option to automatically reload if the profile was modified externally/remotely.

  • Fixed a compatibility issue with some FTP clients.

  • Added a new option to disable automatically notification dismissing.

  • The update notification is now shown as a banner instead of an alert window.

  • Bug fixes.

Version 3.0.6

  • Optimizations for no network error handling.

  • Reduces CPU usage on idle.

  • Fixed a bug while enabling MitM with a new certificate.

  • Fixed crashes on macOS 10.11.

Version 3.0.5

  • CPU usage optimizations (50% reduced for high throughout).

  • Enabled Hardened Runtime to get enhanced security protections in macOS Mojave.

  • Add more notes for rule evaluating stage.

  • may flood ping when network is unstable, which causes a high CPU usage of Surge. We added a mechanism to limit ICMP throughput in this version.

Version 3.0.4

Version 3.0.3

  • Supports new iCloud container for Surge iOS migration.

  • The MitM feature is now compatible with Android system. Please regenerate an new CA certificate before using with Android.

  • Fixed some UI issues in Dashboard.

  • Fixed a bug that MitM may refuse to enable after modifying settings.

  • Fixed a bug that br decompress may fail.

  • Fixed a bug that the menu item may use a wrong color if the accent color of system isn't blue.

  • Fixed the JSON viewer color issue in the Dark Mode.

  • Minor bug fixes.

Version 3.0.2

  • Allows import the profile from a URL.

  • Fixed an issue that the HTTP capture button may show wrong state in Dashboard.

  • Fixed an issue that Dashboard doesn't show User-Agent as the process name while connecting to iOS device.

  • Fixed an issue that the bandwidth of processes may be inaccurate.

  • Fixed an issue that the DEST-PORT rule may not be parsed.

  • Fixed an issue that ruleset can't be used with logical type rule.

Version 3.0.1

  • Fixed an issue that TFO option will not be saved.

  • Fixed an issue that UDP relay option shows wrong state.

  • Fixed some i18n issues.

  • Fixed crashs on macOS 10.11.

  • Save proxy declarations with legacy style (custom) if the proxy is written in legacy style in the text file.

  • Other minor bug fixes.

Version 3.0.0

Surge Mac V2

Version 2.6.7

  • Fixed a compatibility issue with 304 response.

  • Fixed a Dashboard crash.

Version 2.6.6

  • Fixed a compatibility issue with 304 response.

  • Fixed an issue that Dashboard may not use the correct encoding to decode text body.

Version 2.6.5

  • Bug fixes.

Version 2.6.4

  • Bug fixes.

Version 2.6.3

Version 2.6.2

  • Fixed an issue that the UDP mode with AEAD ciphers doesn't work.

  • Bug fixes.

Version 2.6.1

  • Surge now allows expired DNS answers for performance reasons. See 'Optimistic DNS' section in for more information.

  • Performance improvements.

  • Fixed an issue that UDP traffics are not included in the real-time speed.

  • Supports hardware acceleration for AES-GCM encryption.

  • Supports NAT64 in a pure IPv6 network. (Previous versions already supported DNS64)

Version 2.6.0

  • Supports using Surge Mac as a gateway.

  • A new setup guide view.

  • A new config panel for traffic capture options.

  • Fixed an issue which Dashboard may disconnect unexpectedly under huge pressure.

  • The status bar icon will be red while traffic capture is enabled.

  • Improved TUN interface performance.

  • Enabling TCP Fast Open in macOS 10.14.

Version 2.5.3

  • Supports UDP relay for shadowsocks protocol. A brief introduction in Chinese:

  • You may use Dashboard to view UDP conversations.

  • Dashboard now can save multiple remote machine profiles.

  • Improved the JSON viewer in Dashboard.

  • Added an UI switch for the dns-failed option in FINAL rule.

  • Bug fixes.

Version 2.5.2

  • You may toggle the hidden state of columns in Dashboard now.

  • Supports to export selected rows to csv file.

  • Added a connection duration column in Dashboard.

  • Supports obfs-uri parameter.

  • Improved the benchmark view.

  • Fixed a serious bug in the SOCKS5 proxy implementation.

  • Bug fixes.

Version 2.5.1

  • The MitM enabling switch has been moved to the main menu and isolated from profile.

  • Bug fixes.

Version 2.5.0

  • Added Outbound Mode options: Direct Outbound, Global Proxy and By Rule.

  • Added options for all policy to specify outgoing interface: 'interface' and 'allow-other-interface'.

  • Added all_proxy environment variable for 'Copy Shell Export Command'

  • Supports client-side SSL/TLS certificate validation for HTTPS and SOCKS5-TLS proxy. A config example is here: (DO NOT support editing with UI in this version.)

  • Refined MitM.

  • Concurrently setup connection to host with Round-robin DNS to boost performance.

  • Bug fixes.

Version 2.4.6

  • Supports xchacha20-ietf-poly1305.

  • Bug fixes.

  • HTTP request header and response header can be extracted from TCP connection now. (SOCKS5 and TUN)

  • Enhanced mode can handle all connections now, even for connections initialized with IP address directly.

  • Surge TUN now supports forwarding ICMP packets.

From this version, the minimum system version requirement was raised to macOS 10.11. If you are still using macOS 10.10, please use version 2.4.5.

Version 2.4.5

  • Bug fixes.

  • Improved performance for high concurrency.

  • TCP fast open has been disabled temporarily since there is a serious problem in macOS/iOS kernel.

  • Dashboard will display decoded URL query now.

Version 2.4.4

  • Supports obfs=tls for shadowsocks protocol.

  • Refined the proxy edit panel.

  • Added Simplified Chinese language.

Version 2.4.3

  • Supports obfs=tls for shadowsocks protocol.

  • Refined the proxy edit panel.

  • Added Simplified Chinese language.

Version 2.4.2

  • Fixed an issue that enhanced mode may not be closed properly when switching to a profile without dns-server.

  • Fixed an issue that managed profile updating and license info are unavailable while enhanced mode enabled.

  • When the necessary port is used by another process, the error alert will show which process is using the port.

  • Fixed an issue that map local items can't be edited with UI.

  • Fixed an issue that system proxy settings may not be reset properly.

  • Auto URL test group will execute a retest immediately after the selected policy has failed.

Version 2.4.1

  • Bug fixes.

Version 2.4.0

  • Supports enterprise license and profile management.

  • Fixed a bug that some fields are unavailable in the configuration panel in some cases.

  • Fixed a bug that the FINAL rule can't be edited.

  • Fixed a bug that you may not be able to use custom storage path for profiles.

  • The interface related options are no longer controlled by profile. Sorry for the repetitive changes.

  • You may use $1, $2 to use the matched string in the value while using header rewrite.

  • Added an option for HTTP/HTTPS proxy: always-use-connect. When it is true, Surge will use CONNECT method for plain HTTP requests.

Version 2.3.2

  • Added a option to control whether show proxy error notification.

  • Fixed a problem that Dashboard show data doesn't exist error.

Version 2.3.1

  • Added a wizard to install CA’s root certificate for iOS simulator.

  • Connectivity quality is now an option. (Not show by default)

  • Line comments in [Rule] section in profile file is now presented in UI.

  • You may add proxy rule with Dashboard by right-clicking the request or process.

  • Dashboard will always open a new window for local machine, instead of asking. You may use "File" menu to connect to a remote machine.

  • Added a patch mechanism for adjusting settings for managed config. See manual for more information:

Version 2.3.0

  • Completely redesign the configure interface. You may configure every function with UI now.

  • Proxy benchmark is now moved to main application from Dashboard.

  • New feature: Header rewrite. See manual for more information:

  • You may switch profile with command line now: surge-cli switch-profile profilename.

Version 2.2.4

  • Notifications presented by Surge will be removed from Notification Center automatically.

  • The interval of attempts to refresh managed config changes to one hour from one minute. (After config expired)

  • Supports new encryption methods for shadowsocks-libev 3.0.

  • Optimized Dashboard performance.

  • Supports TCP Fast Open for shadowsocks proxy. You need add "tfo=true" flag in [Proxy] section to enable the feature. You may use benchmark to confirm TFO is working.

  • You can sort benchmark results now.

  • You may choose to reload config after managed config updated.

Version 2.2.2

  • Fixed a bug when using SOCKS5 without authorization.

Version 2.2.1

  • You may use Dashboard to benchmark proxies now.

  • Fixed "Too many open files" error by raising limit to 2048.

  • Fixed a bug in SOCKS5 with authorization.

  • Fixed a bug that managed config may refresh continuously.

Version 2.2.0

  • Map local function is now available.

  • Adds notifications when proxy encounters errors.

  • Network changed notification will show service name instead of BSD name now.

  • Fixed a bug that Dashboard may show the incorrect state of body dump.

  • Changes for HTTPS and SOCK5-TLS proxy:

    • Option 'skip-common-name-verify' is deprecated.

    • Add a new option 'skip-cert-verify' to skip certificate verify completely.

    • Add a new option 'sni' to customize SNI field while handshaking. You may use 'sni=off' to disable SNI.

  • New rule type: PROCESS-NAME, USER-AGENT and URL-REGEX.

  • You can use simple wildcard matching (? and *) for PROCESS-NAME rule, local DNS mapping and MitM hosts.

  • Dashboard supports display POST form data in a table view.

  • You may let Surge reload config by sending SIGHUP. You can use command 'killall -HUP Surge' or 'surge-cli reload'.

  • Managed configuration is supported now.

  • Add a new option 'skip-server-cert-verify' for MitM.

Version 2.1.4

  • Fixed a bug that helper may crash on macOS 10.10.

  • Add a option to remove Surge helper for troubleshooting.

  • Bug fixes.

Version 2.1.3

  • Fixed a bug that helper may crash on macOS 10.10.

  • Add a option to remove Surge helper for troubleshooting.

  • Bug fixes.

Version 2.1.2

  • New option: Collapse policy group items in menu

  • Fixed a bug that enhanced mode DNS settings may not be reverted.

  • Hold option key to click 'Copy Shell Export Command' to get a command with primary interface IP instead of

  • Bug fixes.

Version 2.1.0

  • New feature: Enhanced Mode

    Some applications may not obey the system proxy settings. Using enhanced mode can make all applications handled by Surge.

  • New rule type: IP-CIDR6

    Example: IP-CIDR6,2005::/16,DIRECT,no-resolve

  • The /etc/hosts file will be reloaded automatically if it has changes.

Version 2.0.13

  • Dashboard supports to use ⌘ + 1,2,3,4 to switch panel.

  • Dashboard Supports handoff with Surge iOS.

  • Fixed a bug that Dashboard may show incorrect process name.

Version 2.0.12

  • Bug fixes.

  • Supported SNI while performing MitM.

  • The original certificate will be resigned and used while performing MitM, instead of generating a new certificate.

Version 2.0.11

  • Rule test cache will be flushed after network switching now.

  • Added a option 'Grey icon if set as system proxy is disabled'.

  • Bug fixes and performance improvements.

Version 2.0.10

  • Surge talks to HTTP proxies with a plain HTTP method for non-HTTPS requests now, instead of CONNECT.

  • Improved compatibility with some HTTP server.

  • Improved compatibility with some DNS server.

Version 2.0.9

  • Dashborad: The height of the detail panel will not change now while switching pages.

  • A notification will show when proxy client access from other machine.

  • Used SF Mono as monospaced font for header and body data display.

  • Supported TCP half-open mechanism.

Version 2.0.8

  • Add a new option 'exclude-simple-hostnames' in the gereral section.

  • Dashborad: Selected row will not be lost while the filter or sort column changed.

  • Dashborad: Fixes some issues in the active panel.

Version 2.0.5

  • Bug fixes.

Version 2.0.3

  • New feature: Show connectivity quality in menu.

    Surge will send a DNS question to all DNS servers concurrently to test physical network connectivity while opening the menu.

  • Fixes a problem that Surge may freeze while opening the menu.

  • Fixes a problem that if a policy group contains duplicate policies, Surge may crash.

Version 2.0.2

  • Dashboard will no longer display process icon in remote mode.

  • Fixes a bug: "Set as System Proxy" option does not work properly if only SOCKS service is enabled.

  • Fixes a bug: Dashboard can't add a rule with no-resolve option on and comment not empty.

  • Minor bug fixes.

Version 2.0.1

  • Bug fixes