Surge Mac Release Notes

Version 5.7.3

  • Now you can see the number of times a rule has been used in the rule list.

  • Optimized the implementation method of blocking QUIC traffic to increase the likelihood of clients correctly falling back.

  • The Smart group will use the SUBSTITUTE policy (DIRECT) instead of failing directly when there are no sub-policies.

  • Fixed an issue where the server-cert-fingerprint-sha256 parameter was not effective for TLS-like protocols with sni=off settings.

  • Added a new rule type HOSTNAME-TYPE, used to determine the type of request hostname. Optional values are: IPv4, IPv6, DOMAIN, SIMPLE. (SIMPLE refers to hostnames without a dot, such as localhost)

  • Optimized DNS request logs. Now more information is displayed. Additionally, if DIRECT policy connects directly without triggering DNS in the rule system, related DNS logs can still be shown.

  • When deleting a policy that is being used by a policy group, it is now allowed to delete it directly and automatically remove it from all policy groups.

  • Bug fixes and other Improvements.

Version 5.7.2

  • Optimize the matching performance of ASN rules in the rule set.

  • Fix the issue where FINAL rules cannot be edited through UI.

  • Fix the problem that invalid cron expressions would cause scripts to be executed repeatedly.

  • Optimized the management mechanism of the script engine.

  • Other minor issues fixed.

Version 5.7.1

  • Optimize the matching performance of small rule sets, especially evident on older model CPUs.

  • The external resource update page can display error information generated by rule set processing.

  • Automatically ignore invalid empty lines in the rule set.

  • Corrected the issue where applying temporary rules and then experiencing a policy change does not disrupt existing connections.

  • Corrected the issue when using Ponte policy within Smart group, if the target device is itself, it failed to automatically switch to DIRECT policy.

  • Corrected the problem of incorrect time displayed in request logs for Ponte device requests.

  • Corrected crashes that may occur when external policy groups change.

  • Fixed an issue where configuration upgrade functionality did not correctly take effect for managed configurations and enterprise configurations.

  • During Smart group initialization phase, no longer displays most frequently used tags to avoid misunderstanding.

Version 5.7.0

Smart Group

This is a new type of policy group, driven by our carefully designed algorithm engine, which can automatically select the appropriate policy from the sub-policies of this policy group. The goal of the Smart policy group is to replace the original automatic testing groups (url/load-balance/fallback), greatly optimizing the experience while minimizing the need for manual intervention in policy groups. Users only need to put the available policies into this group.

For details, see:

Rule System

  • Overall performance optimization of the rule system.

  • Significant optimization of the indexing algorithm in large domain rule sets, improving the search efficiency by more than ten times for rule sets with more than 100,000 rules.

  • Corrected the issue where sub-rules of logical rules within a rule set could not be covered by the no-resolve and extended-matching parameters of the rule set.

  • Added a new rule type DOMAIN-WILDCARD, supporting ? and * domain name matching.

  • DOMAIN-SET and RULE-SET are changed to strict validation. If there are invalid lines in the file, the entire rule set will be invalidated to avoid problems caused by misuse.


  • The behavior of the ipv6-vif parameter has been modified. When set to always, IPv6 functionality will be enabled even if ipv6=true is not set.

  • Added a warning for the ipv6-vif=always parameter.

  • Adjusted the automatic retry mechanism. Accessing IPv6 addresses in a non-IPv6 network will no longer enter the retry process, and the request will fail immediately (solving the problem of some applications stalling when IPv6 VIF is enabled in a non-IPv6 environment, but the application will still continue to send IPv6 requests).

Other Optimizations

  • Enhanced $, adding support for media resources, sound hints, and automatic dismissal.

  • Optimized WireGuard failure handling.

  • Reduced the power consumption of the TUIC protocol during sleep.

  • Improved the precision of time statistics in the request log system, now accurate to µs level.

  • Optimized various abnormal retry mechanisms, avoiding high resource usage caused by continuous retry in the face of some specific problems. For operations that need to be retried continuously (such as WireGuard reconnection, Ponte server reporting to iCloud), Surge will now retry after 0.1s, 0.5s, 1s, 5s, 10s, 30s after an error.

  • Optimized the caching system for external resources.

  • Added the profile line modifier #!REQUIREMENT.

Detail Adjustments

  • Limited the length of logs that can be written to request notes in debug mode by scripts.

  • Changed the default UDP test target to

  • If incorrect types of fields are passed when using API in scripts, it will result in script errors.

  • After the script is completed or times out, unfinished $httpClient will no longer call the callback function.

Issue Fixes

  • Fixed the issue where the HTTP Body captured from remote devices could not be read in the Dashboard.

  • Fixed the problem where Header Rewrite rules could not match URLs based on the Host field.

  • Corrected the issue where ip-version and tos parameters could not take effect when testing proxies.

  • Fixed the crash issue caused by mistakenly passing null when executing scripts via HTTP-API.

Version 5.6.0

New Feature

  • Mock (Map Local) feature fully enhanced.

    • Added data types such as text, tiny-gif, base64 for inline direct data return.

    • Added status-code parameter

    • UI related configurations have not been updated yet. For usage methods, see the documentation:

  • When the parameter encrypted-dns-follow-outbound-mode=true is configured, if a DoH/DoQ/DoH3 connection matches a proxy server using a domain name, and if there is a DNS Local Mapping record for that proxy server's domain name containing an IP address or traditional DNS server, then it is permissible to query through that proxy server. (Querying DNS through a proxy server will break CDN optimization, leading to severe slowness when loading images and videos. Unless there are very special requirements and it is not necessary to configure in this way, domain rules should be used to ensure requests are directly queried by the proxy server.)

  • Added feature Body Rewrite, see documentation for details: Added recognition for STUN packets, which can be matched using PROTOCOL,STUN. Similar to QUIC, to ensure compatibility, PROTOCOL,UDP can also continue to match STUN traffic.


  • Optimized request logging. Now the specific rules matched for URL Rewrite and Header Rewrite will be displayed.

  • Adjusted the logic of how the DNS engine handles empty results. Now when multiple DNS servers are configured, it no longer waits for all servers to respond with empty results in order to avoid additional waiting when AAAA records do not exist. (However, since the behavior of DNS servers may vary in different environments, observe whether this change causes side effects; please provide feedback if issues arise causing abnormal results.)

  • Canceled warning notifications when ICMP exceeds limits


  • Enhanced compatibility when decompressing HTTP Body.

  • Fixed a crash in Surge caused by passing some incorrect types of parameters in scripts.

  • Adapted to new system restrictions, fixed the issue where selecting to display the main window is ineffective in some cases

  • Fixed compatibility issues with non-https WebSocket in proxy mode and the new version of Safari

Version 5.5.0


  • Added several new official modules; official modules can now be dynamically updated.

  • Modules have a new classification field for convenient access and categorization in the UI.

  • Modules now accept parameter tables, supporting multiple parameters. Parameters will be used to modify module content through text replacement.


  • New script execution engine. Optimized execution performance and memory usage.

  • $httpClient has added several practical parameters. For more details on the updates above, see the documentation.


  • New parameter: always-raw-tcp-keywords. For usage, refer to documentation.

  • Added SRC-PORT rule for matching client port numbers.

  • IN-PORT/SRC-PORT/DEST-PORT three rules are categorized as port number rule types, supporting three kinds of expressions:

    • Directly writing the port number, such as IN-PORT,6153

    • Port number closed interval: such as DEST-PORT,10000-20000

    • Using >, <, <=, >= operators, such as SRC-PORT,>=50000

  • The UI can now maintain pure empty lines from original configurations after editing.


  • Corrected a detail issue with QUIC flow control and optimized latency performance for Ponte/TUIC/Hysteria2 protocols.

  • After editing a single rule, the notification-related parameters will be retained.

Version 5.4.3

  • Rewrote the virtual IP database, now the database can automatically clean up data based on the last time of use.

  • Fixed some issues that may occur when using Snell v4 with WireGuard and enabling reuse.

  • For DNS requests with illegal domain names, an empty result response will be generated instead of being directly ignored.

  • tun-included-routes and tun-excluded-routes parameters now supports IPv6 CIDR block when IPv6 VIF is enabled.

  • Support configuring no-resolve for built-in rule sets/Inline rule sets.

  • Surge Ponte connections no longer validate peer addresses to ensure normal operation in certain special scenarios.

  • Bug fixes.

Version 5.4.2

  • Fixed an issue that the built-in rule set LAN failed to correctly trigger DNS resolution.

  • Fixed an issue that could cause a crash when handling some malformed UDP packets.

  • Fixed an issue that the system that could potentially misjudge has been restarted, causing the Fake IP table to be cleared.

  • Fixed a compatibility issue with a specific HTTP server.

  • Compatible with some non-standard SOCKS5 UDP server implementations, adjusted errors to warnings.

  • Other bug fixes.

Version 5.4.1

Rule Engine Optimizations

  • The implementation of RULE-SET and DOMAIN-SET has been completely rewritten. Now, Surge automatically preprocesses and indexes rule sets during resource updates, significantly increasing the matching speed.

    1. There is no longer any difference in performance and memory usage between RULE-SET and DOMAIN-SET types of rule sets, allowing flexible usage.

    2. There is no longer a restriction in DOMAIN-SET rule sets that prevents the use of eTLDs.

    3. The matching speed for DOMAIN, DOMAIN-SUFFIX, IP-CIDR, and IP-CIDR6 rules in RULE-SET has been greatly improved.

    4. A DOMAIN/DOMAIN-SUFFIX rule set with approximately 100,000 entries used to take 100ms for a single match in the old version; now, it only takes single-digit ms.

    5. An IP-CIDR rule set with approximately 10,000 entries used to take about 0.1ms for a single match in the old version. The new version only needs 0.0002ms, an improvement of about 500 times. The performance improvement for IP-CIDR6 rules is even greater.

    6. In the new version, building a regional IP address collection using the IP-CIDR rule set offers the same performance as directly using the internal GEOIP rule.

    7. The Inline Ruleset added in the previous version does not benefit from this optimization, but there is virtually no difference at the scale of hundreds of entries.

    8. In previous versions, rules within a Ruleset were matched one by one from top to bottom. If rules requiring DNS resolution were included, DNS would only be triggered when starting to match that sub-rule. In the new version, if any rule requiring DNS resolution is included in the rule set, DNS resolution will occur before testing that rule set. (In most cases, there is no difference)

  • Main ruleset matching efficiency has been slightly optimized.

  • The efficiency of IP-CIDR6 rules has been significantly improved even in non-indexed situations.

  • RULE-SET rules can now be configured directly with parameters no-resolve and extended-matching, which are equivalent to configuring all sub-rules with these parameters.

  • DOMAIN-SET rule sets also support configuration with extended-matching.

Minor Optimizations

  • Now, when performing MITM, the certificate used for signing will be sent to the client together, to support using intermediate certificates for MITM.

  • All comments (at the beginning and end of lines) can now use #, //, ; three common comment symbols.

  • Profile error message prompt optimization, now it can give the exact line number where the error occurred more accurately.

  • Optimize Surge Ponte error handling process, correct the issue where device information is not automatically updated under certain errors.

  • Bug fixes.

Version 5.4.0

New Features

  • Protocol sniffing

    Requests to port 80 and 443 will wait for the client to send the first packet, then extract the SNI and other information for the rule system to judge.

    • DOMAIN, DOMAIN-SUFFIX, DOMAIN-KEYWORD rules add an optional parameter called extended-matching. When this parameter is enabled, the rule will try to match both the SNI and the HTTP Host Header (or :authority).

    • Added a parameter called always-raw-tcp-hosts, used to forcibly turn off active protocol detection for specific hostnames.

  • New proxy protocol support: Hysteria 2

    Hysteria 2 is a proxy protocol optimized for unstable and packet-loss-prone network environments, based on UDP/QUIC.

  • Automatic QUIC blocking

    Since most proxy protocols are not suitable for forwarding QUIC traffic, Surge will now automatically block QUIC traffic to make it fallback to HTTPS/TCP protocol, ensuring performance. For QUIC traffic that hits the MITM hostname, it will also be automatically rejected.

  • ECN (Explicit Congestion Notification) support for QUIC-based protocols

    Significantly improved the performance of the Vector(Surge Ponte)/TUIC/Hysteria 2 protocol.


  • Reworked HTTP capture functionality

    • The related settings are no longer stored in the configuration, the [Replica] section has been deprecated.

    • Added an automatic shut-off setting after turning on the capture switch, which can automatically stop capturing based on time, size, or the number of requests.

    • Added automatic activation of MITM after turning on the capture switch, which can be additionally turned on for specific hostnames. (Even if the main MITM switch is off).

    • Added an option to only save HTTP/HTTPS requests after turning on the capture switch.

  • Improved compatibility with some non-standard protocols.

  • When testing the Ponte policy, the test URL has been changed from proxy-test-url to internet-test-url.

  • Following the WireGuard protocol standard recommendation, WireGuard handshake packets will now be tagged with 0x88 (AF41) DSCP to increase the success rate.

  • When forwarding UDP packets via WireGuard, it supports retaining the TOS(DSCP/ECN) tag of packets inside the tunnel.

  • Based on the WireGuard protocol standard recommendation, Surge will copy the ECN tag from packets inside the tunnel to packets outside. When receiving packets with an ECN tag, they will be strictly merged according to RFC6040. (ecn=true must be set for the policy).

  • UDP NAT can close the UDP session early based on ICMP messages.

  • Improved PMTU support for QUIC.

Bug Fixes

  • Fixed the issue where the external resources of rule sets needed to be reloaded to take effect after updates.

  • After a network switch, it will forcefully break the original long connection of DoH/DoQ/DoH3 to avoid obtaining results that are not suitable for the current network environment.

  • Fixed the issue where invalid certificates might cause the key store interface to crash.

  • When performing MITM on HTTPS requests that directly connect using an IP address, the IP address should not be sent as SNI, as this might cause compatibility issues.

  • Other bug fixes.

Version 5.3.2

  • Surge Mac is now ready for macOS Sonoma.

  • External resources can now be remotely managed and updated by Surge iOS.

  • Fixed the issue where the location permission request could not be correctly triggered.

  • Surge Web Dashboard upgraded to version 2.0.4.

  • Other improvements.

Version 5.3.1

  • Surge Dashboard now can directly create temporary rules for local and remote Surge instances.

  • Surge Web Dashboard now upgraded to version 2.0.

  • Added Inline Ruleset, which allows the Ruleset to be written directly in the main profile

  • Module enhanced. Modules can now operate [WireGuard *] and [Ruleset *] sections.

  • Added an HTTP API for obtaining CA certificates (DER format): GET /v1/mitm/ca.

  • Fixed that MITM failed records could not be correctly generated.

Version 5.3.0

  • You can now directly access the Remote Dashboard of registered devices through Surge Ponte.

  • The Surge Dashboard can now operate the policy group and outbound options of remote devices.

  • macOS Sonoma now requires location permissions to obtain the SSID. If related rules and subnet settings are used, Surge will prompt for location permissions.

  • Fixed a bug that the override of a policy group cannot be canceled remotely.

  • Corrected the compatibility issue between VIF and specific devices.

  • Surge Ponte improvments.

  • Minor bug fixes.

Version 5.2.3

  • You can now create a new modifiable profile based on an existing profile. In this new profile, the selected sections will reference the corresponding content in the original profile and will automatically synchronize with the original profile. At the same time, unselected sections in the new profile can be modified freely without being affected by the original profile. (The UI for the detached profile feature.)

  • The detached profile now can include the Enterprise profile.

  • Fixed the issue that it was impossible to connect when the SSH server configured a banner.

  • You can now use the UI to edit ShadowTLS parameters.

  • Optimize performance in VIF v1 mode for ARM64 architecture. When the VIF mode is set to automatic, the new version will automatically use the v1 engine under M1/M2 processors, with a maximum performance of ~8Gbps, thereby avoiding compatibility and stability issues.

  • Correct the issue where the opening position of the Dashboard main window may be incorrect.

Version 5.2.2

  • Fixed the problem where there might be incorrect prompts about system proxy settings being modified by other applications when there is no valid network.

  • Fixed some issues that may occur when using TUIC v5 as the underlying-proxy.

  • Fixed the issue where if WebSocket is enabled, it cannot correctly construct a WebSocket request when directly using an IPv6 address as the vmess hostname.

  • Provide clearer error prompts when the SOCKS5 server does not support UDP relay.

  • Bug fixes.

Version 5.2.1

  • Surge Ponte now can work in LAN-only mode when NAT type doesn't meet the requirement. Devices on same LAN can still access.

  • The connection limiter mechanism added in the previous version has been temporarily removed.

  • Optimize the logic of setting as system proxy function.

  • Fixed a memory leak issue.

  • Bug fixes.

Version 5.2.0

  • Due to the fixed size of macOS network stack memory, when the network stack buffer is exhausted, the kernel will automatically close the program with the highest occupancy to release resources. This problem may occur when using Surge to take over P2P downloaders. This version will automatically check for this issue and enter safe mode automatically.

  • Surge VIF engine has been upgraded to v3, no longer relying on Packet Filter (pf), solving compatibility issues with virtual machines and network sharing functions. At the same time, connection number limits have been added to avoid system resource exhaustion caused by excessive concurrent requests.

  • Add a connection limiter for single processes and single devices to avoid consuming large amounts of resources for individual devices.

  • Support for QUIC's PMTU discovery, which improves the performance of Surge Ponte and TUIC protocols.

  • Optimize error handling logic of QUIC-based protocols.

  • When forwarding UDP packets using TUIC v5, follow the DF flag of the IP packet. Avoid the issue that can occur when visiting the QUIC website with TUIC v5.

  • Other bug fixes and optimizations.

Version 5.1.1

  • Added support for TUIC v5 protocol.

  • Optimized the performance of Surge Ponte/TUIC.

  • Optimized the request Note recording when the strategy group is abnormal.

  • Fixed the problem that connection reuse was not done correctly under MITM H2 mode.

  • Fixed the problem that the request of $httpClient/DoH may sometimes be accidentally cancelled.

  • Adjusted the traffic characteristics of Snell v4 protocol.

  • Other bug fixes and optimizations.

Version 5.1.0

Surge Ponte

  • Surge Ponte supports cross-iCloud account sharing.

  • Fixed issues that might occur when accessing HTTP/1.0 servers via Surge Ponte or TUIC protocol. (e.g. ASUS router management page)


  • Icon Library: You can now select icons for your device from a library of about 7000 icons.

  • Fixed an issue that the reuse feature could not work properly under Snell V4.

  • SSH protocol now supports server public key fingerprint pinning, see the manual for usage.


  • $httpClient supports binary mode.

    • The body of the request supports TypedArray.

    • Passing in binary-mode: true in the request parameters allows the return result to be returned as TypedArray.

  • Fixed the problem that http-request type scripts could not use binary data directly as response.


  • Policy group adds parameter external-policy-modifier, which can be used to adjust external policies.

  • Optimized the request log system

    • Added category marks to the logs.

    • Rule system adds more output for DNS and rulesets.

  • Other bug fixes and optimizations.

Version 5.0.3

  • Added UDP relay support for the VMess protocol

    • Since the VMess server-side supports UDP forwarding by default, there's no need to add extra parameters to use it.

    • Due to design flaws in the VMess protocol, when using VMess to forward UDP traffic, P2P scenarios may not work, such as voice calls, online gaming, etc. Therefore, it is not recommended to use the VMess protocol.

  • SSH protocol now supports specifying the server's public key fingerprint. Check the manual for more information.

  • The external IP address is now obtained through the STUN protocol and no longer relies on

  • The DDNS now uses the secured IPv6 address instead if a temporary one, when IPv6 is selected.

  • Bug fixes.

Version 5.0.2

  • Due to the new privacy restrictions on macOS, if the Wi-Fi BSSID-related features are used, Surge will request location service permissions to read the Wi-Fi BSSID.

  • Shadow TLS v3 is now supported. Append shadow-tls-version=3 to enable it.

  • Surge Mac now supports Adaptive TLS Fingerprint. For more information, please check the community thread.

  • Supports a new parameter external-policy-modifier for groups to modify the parameters of external policies.

  • The new proxy client notification will only be prompted when a real request is received and will no longer be displayed when being port scanned.

  • Bug fixes.

Version 5.0.1

  • The registered Ponte device view is now available when the Ponte switch in off.

  • Fixed a crash while using Surge Dashboard via USB.

  • $httpClient now supports binary mode.

  • Bug fixes.

Last updated