Module is a set of settings to override the current profile. You may use modules to:

  • Tweak settings in a non-editable profile, such as managed profile and enterprise profile.
  • Change part of settings with one tap. For example, you may use a module to enable MitM for all hostnames and adjust the filter temporarily.
  • Use a module written by others to accomplish a particular task. For example, your co-work may share with you a module that rewrites the API requests to a test server.
  • When you share one profile among devices, some settings might need modifying for different scenarios. The enabling state of modules won't be synced to other devices, so you can use a module to fulfill.

Basic Concepts

A module is like a patch to the current profile. The settings of modules have a higher priority than the settings of the profile.

There are 3 types of modules:

  • Internal Modules: Provided by Surge itself.
  • Local Modules: .sgmodule files placed in the profile directory.
  • Installed Modules: Modules installed with a URL.

Write a Module

The syntax of a module is the same as the profile. You are allowed to override these sections:

  • General, Replica, MITM

    • Override: key = value
    • Append to the original value: key = %APPEND% value
    • Insert in the front of the original value: key = %INSERT% value

      You can manipulate the 'hostname', 'skip-server-cert-verify', and 'tcp-connection' fields only in a MITM section.

  • Rule, Script, URL Rewrite, Header Rewrite, Host

    The new lines will be inserted at the top of the original content.

    The rules in a module can only use internal policies: DIRECT, REJECT, and REJECT-TINYGIF.

  • Metadata

    You may add metadata in a module file:

      #!name=Name Here
      #!desc=Description Here

    You may limit a module to specified platform. (Optional)



#!name=MitM All Hostnames
#!desc=Perform MitM on all hostnames with port 443, except those to Apple and other common sites which can't be inspected. You still need to configure a CA certificate and enable the main switch of MitM.

hostname = -*, -*, -*, -*, -*, -*, *
#!name=Game Console SNAT
#!desc=Let Surge handle SNAT conversation properly for PlayStation, Xbox, and Nintendo Switch. Only useful if Surge Mac acts the router for these devices.
always-real-ip = %APPEND% *, *, xbox.*, *

Requirements iOS 5.10.0+ Mac 5.6.0+

The module adds a #!requirement= description, allowing for more complex usage condition restrictions. For example, if the module uses the newly added Body Rewrite feature, it needs to restrict the version of the Surge core.


It also supports logical expressions, such as CORE_VERSION>=20 && (SYSTEM = 'iOS' || SYSTEM = 'tvOS').

The variables that can be used for judgment are as follows:

  • CORE_VERSION: Number, such as 20
  • SYSTEM: String, such as macOS, iOS, tvOS
  • SYSTEM_VERSION: String, such as Version 17.4.1 (Build 21E236)
  • DEVICE_MODEL: String, such as Mac15,8
  • LANGUAGE: String, such as zh-Hans

results matching ""

    No results matching ""