Surge

https://manual.nssurge.com
Admin
Surge is a powerful web development and proxy utility for developers, offering network takeover,...
Tokens:121,584
Snippets:1,263
Trust Score:8.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### GET Modules Response Example

Source: https://manual.nssurge.com/tools/http-api.html

Example JSON response for GET /v1/modules, listing enabled and available modules.

```json
{
    "enabled": [
        "router.com"
    ],
    "available": [
        "Game Console SNAT",
        "Google Home Devices",
        "router.com",
        "MitM All Hostnames"
    ]
}

```

--------------------------------

### GET Capability Response Example

Source: https://manual.nssurge.com/tools/http-api.html

Example JSON response for a GET request to a capability endpoint (e.g., /v1/features/mitm). Shows the enabled state.

```json
{"enabled":true}

```

--------------------------------

### HTTP Rules Configuration Example

Source: https://manual.nssurge.com/rules/http.html

Example configuration block showing two HTTP rules: a USER-AGENT rule matching Instagram* and a URL-REGEX rule matching URLs starting with http://example.com/api/. The rules are placed under the [Rule] section header.

```surge
[Rule]
USER-AGENT,Instagram*,Proxy
URL-REGEX,^http://example\.com/api/,DIRECT

```

--------------------------------

### PROCESS-NAME app bundle mode example

Source: https://manual.nssurge.com/rules/process.html

Matches executable path by prefix for app bundles. Example: /Applications/ChatGPT.app/

```plaintext
PROCESS-NAME,/Applications/ChatGPT.app/
```

--------------------------------

### Start Surge with surge:///start

Source: https://manual.nssurge.com/tools/url-scheme.html

Starts Surge with the selected configuration on iOS. This is the basic URL scheme action for starting Surge.

```plaintext
surge:///start

```

--------------------------------

### PROCESS-NAME filename mode example

Source: https://manual.nssurge.com/rules/process.html

Matches executable file name with wildcards. Example: PROCESS-NAME,Google*

```plaintext
PROCESS-NAME,Google*
```

--------------------------------

### PROCESS-NAME full path mode examples

Source: https://manual.nssurge.com/rules/process.html

Matches full absolute path with wildcards. Examples: /usr/bin/ssh and /Applications/*.app/Contents/MacOS/*

```plaintext
PROCESS-NAME,/usr/bin/ssh
```

```plaintext
PROCESS-NAME,/Applications/*.app/Contents/MacOS/*
```

--------------------------------

### GET Outbound Mode Response Example

Source: https://manual.nssurge.com/tools/http-api.html

Example JSON response for GET /v1/outbound, showing the current outbound mode.

```json
{"mode":"rule"}

```

--------------------------------

### Shadow TLS v2 Configuration Example

Source: https://manual.nssurge.com/policies/tls.html

Example of enabling Shadow TLS v2 on a proxy declaration by appending shadow-tls-password.

```ini
[Proxy]
STLS-SNELL = snell, 1.2.3.4, 443, psk=pwd1, version=4, reuse=true, shadow-tls-password=pwd2

```

--------------------------------

### Client Certificate Configuration Example

Source: https://manual.nssurge.com/policies/tls.html

Example showing how to configure a client certificate for mutual TLS authentication using the client-cert parameter and a corresponding [Keystore] entry.

```ini
[Proxy]
Proxy = https, example.com, 443, client-cert=cert1

[Keystore]
cert1 = base64=<P12 base64 string here>, password=123456

```

--------------------------------

### exit-node configuration example

Source: https://manual.nssurge.com/policies/tailscale.html

Sets the exit-node policy to an explicit peer selector using a full DNS name. The match must be unique and the peer usable; otherwise no exit-node route is installed.

```ini
exit-node = office-exit.example-tailnet.ts.net

```

--------------------------------

### TLS Proxy Configuration Example

Source: https://manual.nssurge.com/policies/tls.html

Example of a proxy declaration using TLS parameters such as sni and server-cert-verify-name.

```ini
[Proxy]
Proxy = https, example.com, 443, sni=cdn.example.com, server-cert-verify-name=example.com

```

--------------------------------

### Shadow TLS v3 Configuration Example

Source: https://manual.nssurge.com/policies/tls.html

Example of enabling Shadow TLS v3 on a proxy declaration, requiring shadow-tls-version=3 and shadow-tls-sni.

```ini
STLS-SNELL = snell, 1.2.3.4, 443, psk=pwd1, version=4, reuse=true, shadow-tls-password=pwd2, shadow-tls-version=3, shadow-tls-sni=example.com

```

--------------------------------

### Map Local configuration example

Source: https://manual.nssurge.com/http/map-local.html

Example configuration showing how to define Map Local rules with various data types and parameters. Each line matches a URL pattern and returns a static response.

```plaintext
[Map Local]
^http://surgetest\.com/json data-type=text data="{}" status-code=500
^http://surgetest\.com/gif data-type=tiny-gif status-code=200
^http://surgetest\.com/file data-type=file data="data/map-local.json" header="a:b|foo:bar"
^http://surgetest\.com/base64 data="dGVzdA==" data-type=base64

```

--------------------------------

### GET Global Outbound Policy Response Example

Source: https://manual.nssurge.com/tools/http-api.html

Example JSON response for GET /v1/outbound/global, showing the default policy for global outbound mode.

```json
{"policy":"ProxyA"}

```

--------------------------------

### External policy list example

Source: https://manual.nssurge.com/policy-groups/policy-including.html

Shows the format of a policy list file referenced by policy-path. Each line is a policy in the same format as the [Proxy] section; blank lines and lines starting with # or // are ignored.

```text
Proxy-A = https, example1.com, 443
Proxy-B = https, example2.com, 443

```

--------------------------------

### POST Switch Profile Request Example

Source: https://manual.nssurge.com/tools/http-api.html

Example JSON request body for POST /v1/profiles/switch (Surge Mac Only) to switch to another profile.

```json
{"name": "Profile2"}

```

--------------------------------

### Source and Port Rules Example

Source: https://manual.nssurge.com/rules/source-and-port.html

Example rule section showing three source and port rules: DEST-PORT, SRC-IP, and DEVICE-NAME. Place these lines under the [Rule] section of a Surge configuration file.

```surge
[Rule]
DEST-PORT,22,DIRECT
SRC-IP,192.168.20.0/24,Proxy
DEVICE-NAME,Kids-iPad,REJECT

```

--------------------------------

### POST Modules Request Example

Source: https://manual.nssurge.com/tools/http-api.html

Example JSON request body for POST /v1/modules to enable or disable modules. Keys are module names, values are booleans.

```json
{
    "router.com": false,
    "Google Home Devices": true
}

```

--------------------------------

### AnyTLS Proxy Configuration Example

Source: https://manual.nssurge.com/policies/anytls.html

Example of configuring an AnyTLS proxy in Surge. The password parameter is required and must match the server setting. The reuse parameter is optional, defaults to true, and can be disabled with reuse=false.

```ini
[Proxy]
Proxy-AnyTLS = anytls, 192.168.20.6, 443, password=pwd

```

--------------------------------

### POST Policy Group Test Response Example

Source: https://manual.nssurge.com/tools/http-api.html

Example JSON response for POST /v1/policy_groups/test, showing the available policies after testing.

```json
{
    "available": [
        "ProxyA",
        "ProxyB"
    ]
}

```

--------------------------------

### Log network state on engine start

Source: https://manual.nssurge.com/scripting/event.html

Logs the network state once the engine has started. The engine-started event fires after the Network Extension and active profile are fully initialized, so $network is ready to read.

```javascript
// on-start = type=event,event-name=engine-started,script-path=start.js

console.log(JSON.stringify($network));

$done();

```

--------------------------------

### Install configuration on macOS with surge:///install-config

Source: https://manual.nssurge.com/tools/url-scheme.html

Installs a configuration from a URL on macOS. The URL should be percent-encoded. The surgeconfig scheme is supported for compatibility on macOS 6.7.0+.

```plaintext
surge:///install-config?url=x
surgeconfig:///install-config?url=x

```

--------------------------------

### underlying-proxy example with relay

Source: https://manual.nssurge.com/policy-groups/parameters.html

Sets up a proxy chain for the whole group: every proxy member connects through the given policy. The example shows a relay proxy and a subscription group using it.

```ini
[Proxy]
Relay = snell, relay.example.com, 443, psk=pwd, version=5

[Proxy Group]
Subscription = url-test, policy-path=https://example.com/nodes, underlying-proxy=Relay

```

--------------------------------

### Snell proxy policy example

Source: https://manual.nssurge.com/policies/snell.html

Example of a Snell proxy policy declaration with version 4, including the required psk parameter and explicit version.

```ini
[Proxy]
Proxy-Snell = snell, 1.2.3.4, 8000, psk=password, version=4

```

--------------------------------

### Example [General] section configuration

Source: https://manual.nssurge.com/profile/general.html

A sample [General] section showing common keys: loglevel, dns-server, skip-proxy, and test-timeout. All keys are optional and case-insensitive.

```ini
[General]
loglevel = notify
dns-server = 223.5.5.5, 114.114.114.114
skip-proxy = 192.168.0.0/16, 10.0.0.0/8, localhost, *.local
test-timeout = 5

```

--------------------------------

### GET Select Group Option Response Example

Source: https://manual.nssurge.com/tools/http-api.html

Example JSON response for GET /v1/policy_groups/select?group_name=GroupNameHere, showing the current option of a select group.

```json
{"policy": "ProxyA"}

```

--------------------------------

### JQ body rewrite example

Source: https://manual.nssurge.com/http/body-rewrite.html

Example of using a jq expression to remove headers starting with 'X-' from a JSON response body.

```plaintext
http-response-jq ^http://httpbingo.org/anything '.headers |= with_entries(select(.key | test("^X-") | not))'

```

--------------------------------

### URL Rewrite configuration example

Source: https://manual.nssurge.com/http/url-rewrite.html

Example configuration showing the three rule types (header, 302, reject) in a single [URL Rewrite] section. Each rule has a regex, replacement, and type; if type is omitted, header is used.

```ini
[URL Rewrite]
^http://www\.google\.cn http://www.google.com header
^http://yachen\.com https://yach.me 302
^http://ad\.com/ad\.png _ reject

```

--------------------------------

### URL-REGEX Rule with Commas Quoted

Source: https://manual.nssurge.com/rules/http.html

Example of a URL-REGEX rule where the value contains commas, so it is wrapped in double quotes. The rule matches URLs starting with http://example.com/(a|b),?c and sends them to Proxy.

```surge
URL-REGEX,"^http://example\.com/(a|b),?c",Proxy

```

--------------------------------

### GET /v1/profiles (Mac Only 4.0.6+)

Source: https://manual.nssurge.com/tools/http-api.html

Get all available profile names (Mac only).

```APIDOC
## GET /v1/profiles (Mac Only 4.0.6+)

### Description
Get all available profile names (Mac only).

### Method
GET

### Endpoint
/v1/profiles

### Response
#### Success Response (200)
- (array) - List of profile names.
```

--------------------------------

### HTTP proxy types example

Source: https://manual.nssurge.com/policies/http.html

Example proxy declarations for the three supported HTTP proxy types: plain HTTP, HTTPS, and HTTP/2 CONNECT. The h2-connect type requires no credentials in this example.

```ini
[Proxy]
ProxyHTTP = http, 1.2.3.4, 443, username, password
ProxyHTTPS = https, 1.2.3.4, 443, username, password
ProxyH2 = h2-connect, example.com, 443

```

--------------------------------

### Example [Proxy] section with HTTPS, Shadowsocks, and Snell

Source: https://manual.nssurge.com/policies/overview.html

Example [Proxy] section declaring three proxy policies: an HTTPS proxy, a Shadowsocks proxy, and a Snell proxy. Shows the use of positional arguments (hostname, port) and key=value parameters for protocol-specific options.

```plaintext
[Proxy]
ProxyHTTPS = https, 1.2.3.4, 443, username, password
ProxySS = ss, 1.2.3.4, 8388, encrypt-method=chacha20-ietf-poly1305, password=pwd
ProxySnell = snell, 1.2.3.4, 8000, psk=pwd, version=5

```

--------------------------------

### POST Kill Request Example

Source: https://manual.nssurge.com/tools/http-api.html

Example JSON request body for POST /v1/requests/kill to kill an active request by its ID.

```json
{"id": 100}

```

--------------------------------

### POST Policies Test Request Example

Source: https://manual.nssurge.com/tools/http-api.html

Example JSON request body for POST /v1/policies/test to test policies with a URL.

```json
{"policy_names": ["ProxyA", "ProxyB"], "url": "http://bing.com"}

```

--------------------------------

### AND logical rule example

Source: https://manual.nssurge.com/rules/logical.html

Combines two sub-rules with AND: matches if both the source IP and domain suffix match. Routes to DIRECT policy.

```surge
AND,((SRC-IP,192.168.1.110),(DOMAIN-SUFFIX,example.com)),DIRECT
```

--------------------------------

### Tailscale Policy Line Example

Source: https://manual.nssurge.com/policies/tailscale.html

Example policy line configuring a Tailscale proxy named 'Office Tailnet' with section-name 'office' and test-timeout of 8 seconds. The section-name parameter is required and must reference an existing [Tailscale <name>] section with exactly one login method.

```plaintext
[Proxy]
Office Tailnet = tailscale, section-name=office, test-timeout=8

```

--------------------------------

### POST Policy Group Test Request Example

Source: https://manual.nssurge.com/tools/http-api.html

Example JSON request body for POST /v1/policy_groups/test to test a group immediately.

```json
{"group_name": "GroupA"}

```

--------------------------------

### Surge rule composition example

Source: https://manual.nssurge.com/rules/overview.html

Illustrates the three-part structure of a Surge rule: TYPE, VALUE, and POLICY, with two example rules.

```text
           TYPE,          VALUE,          POLICY
Example:   DOMAIN-SUFFIX, apple.com,      DIRECT
           IP-CIDR,       192.168.0.0/16, ProxyA

```

--------------------------------

### Wildcard mapping with *.dev

Source: https://manual.nssurge.com/dns/local-dns-mapping.html

Uses wildcards * (any sequence) and ? (single character) with simple string matching against the whole hostname. For example, *google.com matches google.com, foo.google.com, and bargoogle.com; *.google.com does not match google.com.

```ini
[Host]
*.dev = 6.7.8.9

```

--------------------------------

### PROCESS-NAME rule example

Source: https://manual.nssurge.com/rules/process.html

Example of a PROCESS-NAME rule that assigns the Telegram process to the Proxy policy. This rule is Mac-only and does not support pre-matching.

```plaintext
[Rule]
PROCESS-NAME,Telegram,Proxy

```

--------------------------------

### GET /v1/scripting

Source: https://manual.nssurge.com/tools/http-api.html

Lists all the configured scripts.

```APIDOC
## GET /v1/scripting

### Description
List all the configured scripts.

### Method
GET

### Endpoint
/v1/scripting

```

--------------------------------

### Surge Profile Example with [General], [Proxy], and [Rule] Sections

Source: https://manual.nssurge.com/profile/format.html

Example of a Surge profile in INI-like format, showing the [General], [Proxy], and [Rule] sections. The [Rule] section is ordered, so line order affects behavior.

```ini
[General]
loglevel = notify

[Proxy]
ProxyA = http, 1.2.3.4, 80

[Rule]
DOMAIN-SUFFIX,example.com,ProxyA
FINAL,DIRECT

```

--------------------------------

### Custom control server with custom resolver

Source: https://manual.nssurge.com/policies/tailscale.html

Configures a Tailscale policy that uses a custom control URL and a custom DNS server. Requires an auth key and a hostname.

```ini
[Tailscale private-tailnet]
auth-key = tskey-auth-example
control-url = https://control.example.com
hostname = surge-private
dns-server = 100.64.0.53

```
Tokens:
Raw