Surge 5

New Features - Added a full-featured Terminal to Surge iOS, providing CLI-based diagnostics, rule explanations, policy-group inspection, command completion, and history. - Added MASQUE proxy support using HTTP/3 CONNECT and CONNECT-UDP. - HTTP/2 CONNECT proxies can now relay UDP traffic with `udp-relay=true`. - TrustTunnel can now use HTTP/3 transport with `h3=true`. - Added group-level proxy chaining. Policy groups can connect concrete proxy members through an underlying proxy. - Added a Prometheus-compatible `/metrics` endpoint to the HTTP Controller. - Added a graphical Policy Priority editor for Smart Groups. - Added event-script support for `engine-started` and `profile-reloaded`. - Added notification controls for proxy clients, scripts, and rule matches. - Added Arctic and Pulse app icons. Tailscale - Added peer-relay support through eligible tailnet devices, with Direct → Peer Relay → DERP priority and runtime latency information. - Interactive sign-in now supports tailnets requiring administrator device approval. - Improved interrupted sign-in recovery by reconnecting and continuing the existing authorization flow. - Improved compatibility with the Tailscale administration console and version-gated operations. - Fixed connectivity after the control server assigns a new tailnet address. - Improved recovery after network changes, UDP binding failures, expired connections, and multi-peer configurations. #### Profiles, Includes, and Rulesets - `#include` directives can now be freely combined with regular section content. - Sections using multiple or mixed includes are presented as read-only when their write-back destination is ambiguous. - Added wildcard detached-section includes for `[Ruleset *]`, `[WireGuard *]`, and `[Tailscale *]`. - Added `DEVICE_NAME` to the profile environment for use in `#!REQUIREMENT`. - Added diagnostics for missing WireGuard and Tailscale configuration sections and clarified named-include behavior. - Local and inline rulesets can now be edited graphically on macOS and iOS. - Rulesets can reference other inline rulesets and external `RULE-SET` or `DOMAIN-SET` sources. - Circular ruleset references are rejected with a clear reference chain. - The ruleset editor now better preserves blank lines, comments, disabled rules, and source locations. - Fixed rules created inside rulesets or logical rules retaining an unintended hidden policy value. - Improved selection of the appropriate write-back target when mixed includes are used. - Fixed `[General]` values containing `#`, `//`, or `;` being altered after saving. - Profiles changed on disk or through iCloud now reload automatically, while invalid updates leave the working configuration active. - Module installation state is no longer governed directly by iCloud. - Cloud synchronization now excludes `.git` and `node_modules`. UI and Editing - The bottom tab bar remains visible during navigation to avoid UIKit transition glitches. - The Script Editor now uses a dedicated modal interface with an improved toolbar and keyboard layout. - Remote Controller and Ponte Diagnostics are available for all Ponte devices, including shared devices. - Improved policy-group icon handling across themes and profile reloads. - Virtual IP records and search results now use self-sizing rows. - Fixed policy groups using an underlying proxy being unavailable from the UI. - Improved module error reporting for download, parsing, writing, and installation failures. Networking and Reliability - `[Host]` domain aliases can specify a dedicated DNS server. - Fixed recursive HTTP/3 timer processing that could cause stack overflow. - Fixed QUIC connections stalling after receive-side backpressure. - Fixed long-running Ponte and Vector sessions eventually exhausting their ability to open relayed streams. - Improved MITM certificate generation and certificate-chain handling. - Fixed several additional crashes and minor issues.

What's New Surge as MTProto Server - Surge now can operate as an incoming MTProto proxy server for Telegram. Please read manual for more information: https://manual.nssurge.com/ Tailscale - Added interactive Tailscale sign-in on iOS and macOS. Resolve the issue where some enterprise users are unable to obtain the auth key. - Added automatic Tailscale routing. Surge can discover the tailnet’s MagicDNS suffix and peer IPv4/IPv6 addresses, then automatically route matching domains and peer IP traffic through the corresponding Tailscale policy. - Automatic Tailscale routing is enabled by default and can be disabled with `auto-add-magic-dns-rule = false`. - Improved Tailscale session warm-up and recovery. Sessions now retry MagicDNS discovery after startup failures and network changes without requiring matching traffic to arrive first. - Tailscale sessions now stay active by default. An omitted `idle-keepalive`, `0`, or `-1` keeps the session always active; set a positive value to enable idle teardown. - Tailscale can now begin handling traffic as soon as a valid network map is received, without waiting for the home DERP connection to be established. - Improved recovery after network changes and control-server reconnections by preserving the last known home DERP region and retrying peer handshakes at the appropriate time. - Aligned DERP measurement and selection behavior with official Tailscale client, improving compatibility with custom DERP maps, STUN-only nodes, fallback probes, and temporarily unavailable control connections. - Sensitive values such as authentication keys and authorization URLs are now redacted from verbose Tailscale control logs. TLS - Added `server-cert-verify-name` to independently specify the hostname used for proxy server certificate verification without changing SNI. This parameter applies to all TLS- and QUIC-based proxy protocols. ECN - Reworked ECN configuration and packet handling across QUIC, WireGuard, Tailscale, Ponte, and nested UDP tunnels. - Correctly preserves ECN and DSCP/TOS metadata across IPv4 and IPv6 encapsulation and decapsulation. - For QUIC-based proxy protocols, when ECN is enabled, anomalies will be automatically detected and fallback to non-ECN handling. - ECN is now enabled by default for QUIC-based proxy protocols on supported systems. WireGuard and Tailscale remain disabled by default. Use `ecn=false` or `ecn=true` to override the default explicitly. - Surge Ponte now also has ECN enabled by default, and the `client-use-ecn` parameter has been removed. DNS - Optimized TCP connection establishment for `prefer-v4` and `prefer-v6`. In earlier versions, these two parameters indicated which record to use when a domain name had both A and AAAA records. Now, during the TCP handshake, A or AAAA records are used preferentially; if the handshake cannot be completed within 3 seconds, other records will start to be tried. - Added DNS-over-TCP support. DNS server settings now accept `tcp://hostname[:port]`. iOS - Raised the minimum system requirement to iOS 17. - Reworked Shortcuts and App Intent support and improved the reliability of App Intent operations. - Added manual Suspend and Bypass Suspension controls. The Ponte management page, scripts, and local proxy services remain available while Surge is suspended. - Snell Server can now be configured and used on iOS and tvOS. Codebase Refactoring After more than a decade of development, the Surge codebase has grown into a large and complex project. To further improve reliability, we have introduced AI-assisted code review across the entire codebase. Every code change is independently reviewed by Fable 5, GPT-5.6 Sol, and a human developer before being merged, helping us identify potential security issues, rare crash scenarios, and subtle correctness problems. Due to the large number of updates, please refer to the Mac version release notes for details: https://nssurge.com/support/mac/release-notes

### Tailscale Support Surge now supports Tailscale as a policy. With this feature, Surge can join your Tailscale tailnet directly and route selected traffic through Tailscale peers using the existing Surge rule system. You can use Tailscale IPs, and tailnet-only services together with Surge policies, policy groups, DNS handling, traffic logging, and rule-based routing. Please check the manual for more information: https://manual.nssurge.com/policy/tailscale.html ### Snell v6 Introduced Snell v6, featuring PSK-derived deployment-level protocol diversity that generates unique traffic characteristics for each deployment, reducing reliance on a single protocol fingerprint while preserving Snell’s core goals of performance, deployment simplicity, accurate error reporting, and full TCP semantics. Snell v6 also adds new IPv4/IPv6 network stack controls including dns-ip-preference and multi-address listen support, and is currently available for beta testing. Please check our blog for more information: https://nssurge.com/blog/snell-v6/ ### Codebase Refactoring We have completed a comprehensive review of Surge’s core functionality and resolved numerous implementation issues, edge cases, and long-standing inconsistencies. This ongoing refactoring effort improves maintainability and helps provide a more robust foundation for future development. ### WireGuard WireGuard policies now use a dedicated native RTT test when no DNS server is configured, making them suitable for peer-to-peer access without requiring a reachable test URL. When a DNS server is configured, the policy is treated as a standard outbound proxy and continues to use the regular URL test process. WireGuard runtime information and diagnostics have also been updated to reflect the applicable testing mode. ### Minor Improvements - The Smart Group algorithm has been reviewed and upgraded, fixing several potential issues. - The `header` parameter for the HTTP proxy type can now override original fields, including Host field. - Added Gecko obfuscation support for Hysteria2, configured using the `gecko-password` parameter. - All TLS proxy protocols now support customizing ALPN using the `alpn` field. - When local DNS mapping is specified using server, multiple DNS servers can now be configured. - URL scheme actions are now supported in Surge Mac. Check manual for more information. - Enable the keep-alive mechanism for all QUIC-based protocols ### Other - Optimize the performance of Surge Ponte. - The UI configuration interface has been completed for the recently added proxy protocol parameters, including Tailscale. - Fixed an issue where the `header` parameter did not take effect in HTTP/1.1 CONNECT mode. - Fix some issues when using SF Symbols for policy group icons. - Fixed compatibility issues between DoH3 and some servers.

Adjustments to the Feature Update Subscription for Surge iOS Since the introduction of the feature update subscription mechanism for Surge iOS, we have aimed to maintain a reasonable balance between continuously evolving the product’s capabilities and ensuring a reliable long-term user experience. After evaluation, we have decided to make the following adjustments: 1. All newly added proxy protocol compatibility support in the future will no longer be included within the scope of the feature update subscription, and will be available directly to all users. 2. TrustTunnel, which is currently supported on an experimental basis, will also not be subject to subscription restrictions and can be used directly. We believe that protocol compatibility should be a fundamental capability provided in a stable, long-term manner, rather than a phased incremental feature. This means that, in the future, users will not need to worry about the availability of basic protocol support due to their subscription status; new protocol compatibility capabilities will also be made available to all users more directly and continuously. After this adjustment, subscription updates will focus more on new advanced features, while protocol compatibility itself will be maintained as a long-term foundational capability of the product. At the same time, the proxy protocol ecosystem itself is also constantly changing. Some protocols continue to evolve, while others gradually fall out of mainstream use cases. To ensure the long-term maintainability of Surge’s codebase and the overall quality of the product, we will also take actual usage into account when placing certain legacy protocols into maintenance freeze, or gradually ending support for them in the future. We will handle related adjustments as cautiously as possible and provide explanations in advance, in order to minimize the impact on existing user profiles and user experience. Thank you all for your continued support and feedback. --------------------- * Added HTTP/2 CONNECT proxy support. You can configure HTTP/2-based CONNECT proxy connections via the h2-connect type. * HTTP, HTTPS, HTTP/2 CONNECT, and TrustTunnel proxies now support custom request headers. * HTTP/2 CONNECT and the TrustTunnel proxy now support multiplexing. Because too many sub-connections multiplexed over the same TCP connection may cause performance issues, by default up to 3 sub-connections are allowed. This can be adjusted via the policy parameter `max-streams`. * The storage logic for icon configuration in the iOS version has been adjusted. Now, when the profile is editable, it will preferentially be written into the profile to ensure interoperability with the Mac version. Only when the profile is read-only will a separate UI profile be used for storage. * Fixed an issue where sending SNI did not strictly comply with RFC6066. Now, when an IP address is used as the hostname, the IP address will not be sent as SNI. * Fixed an issue where crashes could occur when using ShadowTLS with certain servers. * Fixed an issue where, when the Logbook contained a very large amount of data, it could not be viewed remotely via the Dashboard. * Other performance optimization and minor enhancements.

(Because the interval since the last subscription feature update was too long, all users whose subscription feature expiration date is after December 11, 2025 have been granted a free 3-month extension.) New subscription feature: Logbook, used to persistently record various events that occur, - Currently includes events such as engine start and stop, network switching, script start and stop, script timeout, etc. - The logbook is specially optimized for script debugging, making it easy to view a script’s input, output, and logs. At the same time, scripts can proactively write content to the logbook using $surge.logbook("content") - Surge Dashboard on Surge Mac can read the logbook content of remote Surge instances, and all script execution details can be accessed remotely Other improvements - Added support for the X25519MLKEM768 post-quantum hybrid key exchange group for all TLS-related features (such as proxy protocols, MITM, DoH/DoT/DoH3) - Improved the $persistentStore management page, adding operations such as search, import/export, and delete all - Refactored memory management for the QUIC protocol to resolve an issue where, under certain circumstances, QUIC-based protocols could experience sudden excessive memory usage that caused Surge to be terminated by the system - Fixed a memory leak when using Trust Tunnel - Fixed a crash that could occur with extremely low probability - Fixed an issue where API requests could get stuck when HTTP API TLS is enabled - Fixed some UI detail issues