Surge TestFlight Feed

Profile System Updates - Added wildcard detached-section includes for [Ruleset *], [WireGuard *], and [Tailscale *]. A single #!include can now load all matching named sections from another local or remote profile file. - Added DEVICE_NAME to the profile environment, enabling device-specific conditions in #!REQUIREMENT. - [Mac] The current Reload Profile option will compare the differences between the old and new profiles and apply only the changes. It will not terminate existing active connections unless necessary. (Same behavior as editing through the UI previously.) - [Mac] Added a Restart Engine option, which behaves like Reload Profile in the previous version and completely restarts the core once.

Beta Updates ### Surge CLI - Added vmnet status to inspect the VMNET interface configuration, including addresses, prefixes, MTU, and diagnostic table sizes. - Added vmnet arp to inspect IPv4 neighbors learned from Gateway Mode clients. - Added vmnet ndp to inspect the IPv6 neighbor table. - Added vmnet ra to inspect IPv6 Router Advertisement takeover status, including clients, known routers, RA lifetimes, and blacklisted devices. ### macOS - Added a graphical Port Forwarding editor for creating and managing incoming TCP forwarding rules. Listening address, listening port, destination, and outbound policy can all be configured without editing the profile manually. - Gateway-related device actions are now hidden when Gateway Mode is unavailable. - Fixed system proxy settings being applied when using VIF mode without a default route. ### iOS UI - When navigating to a new page, the bottom tab bar is no longer hidden. This change was made to avoid triggering known UIKit UI glitches that can occur when the tab bar is hidden during push transitions. - The Script Editor now opens in a dedicated modal interface, with an updated toolbar, close action, and improved keyboard layout. - Remote Controller and Ponte Diagnostics are now available for all Ponte devices, including devices shared by another iCloud account. - Other UI improvements. ### Other Improvements - Updated the IPv6 fake-IP range to avoid unnecessary browser local-network permission prompts, while retaining compatibility with previously cached addresses. - Proxy connections closed during the protocol handshake now provide a clearer error message, with guidance to verify credentials, encryption methods, and protocol settings. - Fixed rare crashes that could occur when proxy connections were synchronously closed while data was being written. - Fixed recursive HTTP/3 timer processing that could cause a stack overflow under certain conditions.

DNS Updates Host rules now support specifying a dedicated DNS server for domain aliases, for example: foo.com = bar.com, server:https://example/dns-query.

iOS TestFlight Updates New Feature: Terminal You can now operate Surge directly through the CLI on Surge iOS. - CLI mode includes a comprehensive set of debugging and diagnostic tools for troubleshooting. For example, the rule explain command can be used to inspect how rules are evaluated and how policy groups make their decisions. - The new virtual Terminal provides a full interactive experience, including command auto-completion and history. For details on available commands, refer to the Surge Manual or simply run help in the Terminal. Other reasons why you might want to use Surge from the CLI: - It’s cool. Maybe even cooler when you’re using it on an iPhone Fold later this year. - Bringing full CLI capabilities to iOS also lays the groundwork for future AI Agent features on Surge iOS. New Icons: Arctic & Pulse - The former Surge Enterprise icon now has a new name: Arctic, and is available for everyone to use. - Added a new icon: Pulse.

Channel photo updated

Prometheus Metrics Endpoint Surge now provides a Prometheus-compatible metrics endpoint at GET /v1/metrics, making it easy to integrate Surge with Prometheus and Grafana for long-term monitoring and visualization. This is particularly useful for gateway deployments that run continuously. The endpoint exposes cumulative traffic counters for each network interface and policy (surgeinterface_bytes_total and surge_policy_bytestotal), which can be combined with PromQL functions such as rate() for real-time throughput or increase() for traffic usage over any time window. It also provides metrics for the Surge engine’s memory footprint (surgememorybytes), in-flight requests, DNS cache size, active unauthorized-access bans, uptime, and build information. The memory metric can be especially useful on iOS for monitoring Network Extension memory usage over time. The metrics endpoint uses the same authentication mechanism as the rest of the Surge HTTP API. Since Prometheus does not send custom authentication headers by default, the API key can also be supplied through the x-key query parameter: scrape_configs: - job_name: surge metrics_path: /v1/metrics params: x-key: ["<your-http-api-key>"] static_configs: - targets: ["192.168.1.1:6171"]

Group-Level Proxy Chaining Surge now supports the group-level underlying-proxy parameter, allowing you to configure a proxy chain for an entire policy group in one place. Every member of the group will connect through the specified policy, including members imported via policy-path, include-all-proxies, and include-other-group. Chained members are represented as derived policies such as Name (via Relay), each with its own independent latency test result. This means automatic policy groups can select the best node based on its actual performance through the complete proxy chain, rather than the performance of the node alone. The new option is also fully integrated into the policy group editor UI. Previously, similar behavior could be achieved with external-policy-modifier="underlying-proxy=...", but that approach only applied to members loaded through policy-path. The new group-level parameter works with members from all sources, provides explicit misconfiguration reporting, and is available as a first-class option in the UI. The existing external-policy-modifier syntax remains supported for backward compatibility. Please refer to the manual for a detailed comparison and configuration examples: https://manual.nssurge.com/policy-groups/parameters.html

Protocol Updates - Added MASQUE proxy support, using HTTP/3 CONNECT for multiplexed TCP tunnels and CONNECT-UDP for UDP datagrams. - Added UDP relay support to HTTP/2 CONNECT proxies with udp-relay=true. - Added HTTP/3 transport support to TrustTunnel with h3=true.

New Surge Beta Feed on X We’ve launched @SurgeBeta, a new X account for detailed updates on the latest Surge Beta releases. It will stay in sync with our existing Telegram Channel. Follow @SurgeBeta to keep up with the latest Beta changes and improvements.

Surge CLI Updates As Surge CLI becomes a key foundation for integrating AI capabilities with Surge, we are continuing to expand and refine it. The interactive CLI now supports command history and auto-completion, making it significantly more convenient for both everyday use and exploratory workflows. We’ve also added a new set of useful commands, including rule match and rule explain, which let Surge answer a common debugging question without generating any real traffic: “Why would this request go through that policy?” rule match rule match performs a dry-run evaluation against the active rule set and reports the matched rule and final policy. All relevant matching attributes — including hostname or URL, port, process path, source address, client MAC, protocol, and more — can be supplied as key=value options. This makes it possible to reproduce exactly how a specific request or client would be routed. Combined with --raw, it can also be used in scripts to audit an entire list of domains against your current rules. rule explain rule explain goes a step further by showing why a particular policy was selected. It traces the complete policy-group resolution path and reports every decision along the way, including manual selections, automatic test results, overrides, load-balancing decisions, Smart Group selections, the underlying proxy chain, DNS evaluation notes, and timing information. Use rule match for quick checks and scripting, and rule explain when you need to inspect the complete decision path. And there’s more coming: starting with the next iOS TestFlight build, Surge CLI will be able to operate Surge directly on iOS. Stay tuned.

Surge Mac 6.8.0 Surge Mac 6.8.0 has been officially released. This is one of our most substantial updates yet, combining major new capabilities with extensive improvements throughout the networking stack. Highlights include: - Initial adaptation for macOS…

Surge Mac 6.8.0 Surge Mac 6.8.0 has been officially released. This is one of our most substantial updates yet, combining major new capabilities with extensive improvements throughout the networking stack. Highlights include: - Initial adaptation for macOS 27 - Interactive Tailscale sign-in and automatic routing - MTProto server mode for Telegram - Built-in Snell v6 server support - A significantly expanded Surge CLI and new AI Skills - Reworked ECN handling across QUIC, WireGuard, Tailscale, Ponte, and nested UDP tunnels - DNS-over-TCP and improved IPv4/IPv6 connection establishment - UDP-aware Smart Group policy selection - Major improvements to Gateway Mode, Ponte, profiles, cloud sync, external resources, and diagnostics The release also delivers wide-ranging security, correctness, and reliability enhancements across core components—covering everything from malformed-data handling and connection recovery to memory usage, concurrency, and long-running stability. Read the full release notes: https://nssurge.com/support/mac/release-notes

Snell v6.0.0 RC2 When ipv6=false, return a clearer error message when the client explicitly accesses an IPv6 address. https://kb.nssurge.com/surge-knowledge-base/release-notes/snell

Surge Manual Updates The Surge Manual has undergone a comprehensive review and rewrite. Every configuration option has been audited against the latest version of Surge. Outdated settings, deprecated behaviors, and obsolete documentation have been removed to ensure the manual accurately reflects the current implementation. In addition, we’ve expanded the documentation with many new configuration examples, making it easier to understand how different features work and how they can be combined in real-world scenarios. Highlights • Comprehensive review and rewrite of the entire manual. • Audited every configuration option against the latest Surge behavior. • Removed deprecated settings and obsolete documentation. • Improved consistency and accuracy throughout the documentation. • Added many new examples to demonstrate practical configurations. This update ensures that the manual stays aligned with the current version of Surge and provides a more reliable reference for both new and experienced users. https://manual.nssurge.com/

Surge CLI Updates https://nssurge.com/blog/surge-cli-updates/ Surge CLI has been significantly expanded into a comprehensive command-line management and diagnostics interface, with the following new commands: ## New Commands - Added status to display the active profile and its full path, outbound mode, feature states, uptime, and version information. - Added version to display Surge, Core, Controller protocol, operating system, and device versions. - Added dump summary to provide a passive overview of the current network environment, including interfaces, IP addresses, default router, DNS servers, cellular or Wi-Fi information, and configuration warnings. - Added mode to view or switch between Rule, Direct, and Global Proxy modes. - Added global-policy to view or change the policy used in Global Proxy mode. - Added policy-group to list policy groups, inspect their current selections, manually select a policy, or clear an automatic-group override. - Added profile to list, inspect, validate, and switch profiles. Profile listing and validation are available on macOS. - Added module to list modules and enable or disable multiple modules in one operation. - Added feature to inspect and control MitM, Rewrite, Scripting, HTTP Capture, Packet Capture, and Cellular Mode. On macOS, it also supports System Proxy and Enhanced Mode. - Added device to list Gateway Mode devices or inspect an individual device by identifier or MAC address on macOS. - Added reconnect-device to reconnect a specified access-point client from the command line on macOS. - Added script list to display configured scripts and script run to execute a cron script by name, including disabled scripts, while returning its output or exception. - Added log to retrieve up to 10,000 recent log lines from either the persistent log file or the more detailed in-memory log. - Added log watch to continuously stream newly generated, unfiltered logs. - Added logbook to display recent structured Logbook records. - Added script-log to retrieve the log from a specific script execution. - Added benchmark encryption to measure the encryption and decryption performance of the device running Surge, with correctness, integrity, and tamper-detection checks. ## Diagnostic Improvements Existing diagnostic commands have also been improved: - proxy-runtime-status now provides detailed runtime information for Tailscale and WireGuard, including traffic, recent errors, peer handshakes, DERP connections, Exit Node state, peer paths, and MagicDNS information. - Query and diagnostic commands now produce structured, human-readable terminal output by default, while --raw remains available for automation. - Commands that change settings now return the resulting state and properly report failures. System Proxy and Enhanced Mode commands wait for the actual state transition to complete. - Remote Controller passwords can now be supplied through a secure terminal prompt, SURGE_CLI_PASSWORD, or --password-stdin, avoiding exposure in the process command line. - Remote connections now support bracketed IPv6 addresses and include timeouts for stalled connections and finite operations. - Interactive mode now supports quoted arguments and backslash escaping. ## Availability The above updates apply to Surge Mac 6.8.0, Surge iOS 5.21.0, and Surge tvOS 5.21.0. Please notice surge-cli can operate remote instances via --remote. The corresponding updates have also been added to the AI Skills documentation. After the update, AI Agents can automatically gain the new capabilities.

macOS 27 Beta 4 Local Network Issue A small number of users running macOS 27 Beta 4 have reported that Surge may fail to access services on the local network, returning a “No route to host” error. After investigation, we have confirmed that this is caused by an issue with the system’s Local Network permission database. If the problem persists, you can try resetting the Local Network permission database by running: tccutil reset LocalNetwork or wait for a future macOS beta update, as the issue appears to be a system bug.

Surge Ponte Service Notice Over the past three days, a small number of users have reported that Surge Ponte is unable to access iCloud, resulting in synchronization failures. After investigation, we have confirmed that this is caused by a server-side issue with Apple’s CloudKit service rather than Surge itself. The issue has been reported to Apple and can only be resolved by Apple. If you are affected, please allow Apple a few days to resolve the issue. Most affected users are using iCloud China (operated by GCBD), although we have also received a small number of reports from users on the international iCloud service. To reduce our dependency on a single cloud provider, we have also started designing a general Bring Your Own Storage (BYOS) mechanism. Once available, users will be able to use their preferred cloud storage service for both configuration synchronization and Surge Ponte data synchronization. We will share more details as development progresses.

More Details About the Tailscale Update * The new version will automatically add the user’s MagicDNS domain as a highest-priority DOMAIN-SUFFIX rule, such as DOMAIN-SUFFIX,tail123456.ts.net. Therefore, when using MagicDNS for access, there is no need to manually configure the rule. * Surge’s default policy for Tailscale is to start on demand. If there are no active requests for 600 seconds, it will automatically disconnect to avoid unnecessary resource consumption. If you want to stay continuously online like the official client and avoid additional waiting during initialization, you can configure idle-keepalive = -1.

New Feature: 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/others/mtproto.html TL;DR Using MTProto instead of SOCKS or VIF to take over Telegram can: 1. Telegram has a notorious SOCKS5 bug in which it can put an IPv6 destination address into an IPv4 request. The malformed destination causes a large number of invalid connection attempts to be sent to Surge. MTProto avoids this path entirely. 2. Force connections to Telegram servers over IPv6. Telegram’s IPv4 servers have a bug that can easily cause the connection to hang without responding. IPv6 nodes do not have this issue, and MTProto allows the intermediary proxy to determine the specific DC service address. Therefore, setting ipv6=true can resolve this persistent problem. (The proxy server must support IPv6 forwarding.)