Surge Manual

Surge is a network toolbox for developers and advanced users. It can take over device traffic, route requests by rule, forward traffic through proxy servers, customize DNS behavior, decrypt HTTPS traffic for debugging, and automate workflows with scripts.

If you are new to Surge, start with Quick Start, then read Core Concepts. If you already know what you want to configure, use the sidebar as a reference.

Documentation Map

  • Profile: profile structure, includes, modules, comments, and requirement expressions.
  • Traffic Routing: rule syntax and matching order.
  • Policies: built-in policies, proxy policies, protocol parameters, and policy groups.
  • DNS: upstream DNS, encrypted DNS, and local DNS mapping.
  • HTTP Processing: MITM, URL rewrite, header rewrite, body rewrite, and mock responses.
  • Scripting: JavaScript APIs for request, response, rule, DNS, event, and cron scripts.
  • Tools and APIs: Dashboard-related features, Logbook, testing, CLI, HTTP API, and URL schemes.

Core Workflow

  1. Surge captures traffic by system proxy settings, local proxy ports, or Surge VIF.
  2. Surge resolves hostnames with its DNS client and local DNS mapping rules.
  3. Rules match each request from top to bottom.
  4. The matched rule selects a policy or policy group.
  5. HTTP processing and scripting can inspect or modify supported traffic.

Features

  • High Performance, Stability, and Efficiency: Surge can smoothly handle all network traffic with industrial-grade stability using minimum system resources.
  • Flexible Rule System: You can write forwarding rules based on domain names, IP CIDR ranges, GeoIP, process names, protocols, and other request attributes.
  • Proxy Protocol Support: Surge can forward requests through HTTP, HTTPS, SOCKS5, SOCKS5-TLS, Shadowsocks, VMess, Trojan, TUIC, Hysteria 2, AnyTLS, WireGuard, SSH, and other supported protocols.
  • HTTPS Decryption: Decrypt HTTPS traffic with MITM. The certificate generator can help you generate a CA certificate trusted by your operating system for debugging purposes.
  • Local DNS Mapping: Surge supports customized DNS mapping, including wildcards, aliases, and per-domain DNS servers.
  • Policy Group: You can group policies and choose one manually, by latency testing, by fallback behavior, by load balancing, or by subnet.
  • HTTP Rewrite: You can rewrite HTTP/HTTPS requests, map responses to local data, or block requests.
  • Remote Dashboard: Surge Dashboard may connect to remote Surge iOS or Surge Mac instances via USB or network.
  • Full IPv6 Support: Surge works in IPv6 environments.

Surge Mac Exclusive Features

  • Enhanced Mode: Surge can set up a virtual network interface to handle all network traffic for applications that do not explicitly support web proxy.
  • Metered Network Mode: You can control which applications/processes are allowed to access the Internet, which is useful when on metered connections (e.g., cellular networks).
  • Gateway Mode: Surge Mac can be configured as a layer three gateway to handle network traffic for other devices in the same network.

Surge iOS Exclusive Features

  • All functions work on cellular networks.
  • Capture HTTP, HTTPS, TCP, and UDP traffic from apps on your device, even if the app does not follow system proxy settings.
  • Override system DNS settings even on a cellular network and boost performance by querying all DNS servers simultaneously.
  • Monitor and analyze network requests on iOS devices by connecting Surge Dashboard to Surge iOS via Wi-Fi or USB cables. You can even examine cellular network requests when connecting via USB cables.

Understanding Surge

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

results matching ""

    No results matching ""