# Surge Manual

## Overview
Surge is an advanced network toolbox for macOS and iOS: it captures device traffic, routes
requests by rule, forwards traffic through proxy servers, customizes DNS behavior, decrypts
HTTPS traffic for debugging, and automates workflows with JavaScript. This repository contains
the official documentation.

## Entry Points
- README.md: High-level overview and capability map.
- SUMMARY.md: Table of contents for all documentation sections.

## Getting Started
- getting-started/how-surge-works.md: Architecture and request lifecycle.
- getting-started/quick-start.md: First profile walkthrough.
- getting-started/platform-differences.md: Surge Mac vs Surge iOS feature matrix.

## Profile
- profile/format.md: Profile format, sections, includes, comments.
- profile/managed-profile.md: Managed profiles and remote updates.
- profile/module.md: Modules.
- profile/requirement.md: Line requirement expressions.
- profile/keystore.md: [Keystore] section for certificates and keys.
- profile/host-list.md: Host List parameter type.
- profile/general.md: Complete [General] section reference.

## Rules
- rules/overview.md: Rule system overview, evaluation order, option flags.
- rules/domain.md: Domain rules (DOMAIN, DOMAIN-SUFFIX, DOMAIN-KEYWORD, DOMAIN-WILDCARD, DOMAIN-SET).
- rules/ip.md: IP rules (IP-CIDR, IP-CIDR6, GEOIP, IP-ASN).
- rules/http.md: HTTP rules (USER-AGENT, URL-REGEX).
- rules/process.md: PROCESS-NAME rules (Mac).
- rules/source-and-port.md: Source and port rules (SRC-IP, SRC-PORT, DEST-PORT, IN-PORT, DEVICE-NAME, MAC-ADDRESS).
- rules/protocol-and-network.md: PROTOCOL, HOSTNAME-TYPE, CELLULAR-RADIO, CELLULAR-CARRIER, SUBNET and subnet expressions.
- rules/logical.md: Logical rules (AND, OR, NOT).
- rules/script.md: SCRIPT rules.
- rules/ruleset.md: Rule sets (internal, inline, external) and domain sets.
- rules/final.md: FINAL rule.

## Policies and Proxy Protocols
- policies/overview.md: Policy kinds and the [Proxy] section.
- policies/built-in.md: Built-in policies and aliases.
- policies/reject.md: REJECT policy family and pre-matching.
- policies/parameters.md: Common policy parameters and proxy chaining.
- policies/tls.md: TLS parameters, client certificates, Shadow TLS.
- policies/udp.md: UDP relay.
- policies/http.md: HTTP, HTTPS, and HTTP/2 CONNECT proxies.
- policies/socks5.md: SOCKS5 and SOCKS5-TLS.
- policies/shadowsocks.md: Shadowsocks.
- policies/snell.md: Snell.
- policies/vmess.md: VMess.
- policies/trojan.md: Trojan.
- policies/tuic.md: TUIC v4/v5.
- policies/hysteria2.md: Hysteria 2.
- policies/masque.md: MASQUE (HTTP/3 CONNECT and CONNECT-UDP).
- policies/anytls.md: AnyTLS.
- policies/trust-tunnel.md: Trust Tunnel.
- policies/ssh.md: SSH.
- policies/wireguard.md: WireGuard.
- policies/tailscale.md: Tailscale.
- policies/external.md: External proxy program (Mac).

## Policy Groups
- policy-groups/overview.md: Policy group overview.
- policy-groups/select.md: Manual selection group.
- policy-groups/url-test.md: Automatic testing group.
- policy-groups/fallback.md: Fallback group.
- policy-groups/load-balance.md: Load balance group.
- policy-groups/smart.md: Smart group.
- policy-groups/subnet.md: Subnet group.
- policy-groups/policy-including.md: Including external and existing policies.
- policy-groups/parameters.md: Common group parameters and testing mechanics.

## DNS
- dns/overview.md: Surge DNS client behavior.
- dns/dns-server.md: Upstream DNS servers.
- dns/encrypted-dns.md: DoH, DoH3, DoQ, DoT, and DNS over TCP.
- dns/local-dns-mapping.md: [Host] local DNS mapping.
- dns/advanced.md: Fake IP, DNS hijacking, and advanced behaviors.

## HTTP Processing
- http/overview.md: HTTP engine and rewrite pipeline.
- http/mitm.md: HTTPS decryption (MITM).
- http/url-rewrite.md: URL rewrite.
- http/header-rewrite.md: Header rewrite.
- http/body-rewrite.md: Body rewrite.
- http/map-local.md: Map Local.

## Scripting
- scripting/overview.md: [Script] section and script engines.
- scripting/api.md: JavaScript API reference.
- scripting/http-request.md: HTTP request scripts.
- scripting/http-response.md: HTTP response scripts.
- scripting/rule.md: Rule scripts.
- scripting/dns.md: DNS scripts.
- scripting/event.md: Event scripts.
- scripting/cron.md: Cron scripts.
- scripting/generic.md: Generic scripts.

## Device and Network Features
- features/enhanced-mode.md: Enhanced Mode (Surge VIF).
- features/gateway.md: Gateway mode (Mac).
- features/dhcp.md: DHCP server (Mac).
- features/subnet-settings.md: Per-network subnet settings.
- features/port-forwarding.md: Port forwarding.
- features/ponte.md: Surge Ponte device-to-device access.
- features/snell-server.md: Built-in Snell server (Mac).
- features/mtproto.md: Built-in MTProto proxy server.

## Tools and APIs
- tools/dashboard.md: Dashboard and remote controller access.
- tools/logbook.md: Logbook.
- tools/testing.md: Connectivity and throughput testing.
- tools/cli.md: Surge Mac CLI.
- tools/http-api.md: HTTP API and Prometheus metrics endpoint.
- tools/url-scheme.md: URL scheme.
- tools/panel.md: Information panels on iOS and Mac.