Surge Manual

Surge is a network toolbox for macOS and iOS, built for developers and advanced users. It captures device traffic, routes each request by rule, forwards traffic through proxy servers, customizes DNS behavior, decrypts HTTPS traffic for debugging, and automates workflows with JavaScript.

Everything Surge does is controlled by a plain-text profile. If you are new to Surge, start with How Surge Works, then build your first profile with Quick Start.

Capability Map

  • Traffic capture: take over traffic via system proxy settings, local proxy ports, or the Surge virtual network interface. See How Surge Works and Enhanced Mode.
  • Profile & modules: profile syntax, managed profiles, modules, and requirement expressions. See Profile Format and the General section reference.
  • Rule-based routing: match requests by domain, IP, GeoIP, process, protocol, source, and more; combine conditions with logical rules and rule sets. See Rules Overview.
  • Outbound policies: DIRECT, REJECT, and proxy policies with HTTP(S), SOCKS5, Shadowsocks, Snell, VMess, Trojan, TUIC, Hysteria 2, AnyTLS, SSH, WireGuard, Tailscale, and more. See Policies Overview.
  • Policy groups: choose among policies manually, by latency test, by fallback, by load balancing, by subnet, or automatically. See Policy Groups.
  • DNS customization: upstream and encrypted DNS (DoH/DoH3/DoQ/DoT), local DNS mapping, and fake-IP handling. See DNS Overview.
  • HTTP processing: HTTPS decryption with MITM, URL/header/body rewrite, and local response mapping. See HTTP Processing and MITM.
  • Scripting: JavaScript hooks for requests, responses, rules, DNS, events, and cron jobs. See Scripting Overview.
  • Device & network features: gateway mode, DHCP, per-network settings, port forwarding, Surge Ponte device-to-device access, and built-in Snell/MTProto servers. See Gateway Mode and Surge Ponte.
  • Tools & automation: Dashboard, Logbook, connectivity tests, surge-cli, HTTP API, and URL schemes. See Dashboard, CLI, and HTTP API.

Platforms

Surge is available as two products that share the same core engine and profile format:

  • Surge Mac runs as a native macOS app. It adds Mac-specific capabilities such as gateway mode, the DHCP server, process-based rules, the built-in Snell server, surge-cli, and the Surge Dashboard app.
  • Surge iOS runs as a Network Extension VPN, so all functions work on both Wi-Fi and cellular networks. A tvOS version is included with the Surge iOS app.

Most profile options work identically on both platforms. For the consolidated list of platform-specific features and keys, see Platform Differences.

Understanding Surge

We have published an official guidebook to help you understand Surge.

results matching ""

    No results matching ""