Module
Chute supports external module files (.sgmodule) to extend configuration with reusable, shareable rules, scripts, MitM hosts, and DNS mappings. Modules follow the Surge module format.
Modules are defined in the [Module] section:
[Module]
https://example.com/my-module.sgmodule
/path/to/local-module.sgmodule
~/.chute/custom-module.sgmodule
URLs are fetched remotely; paths starting with / or ~ are loaded from the local filesystem.
Module File Structure
A .sgmodule file follows the same syntax as the main configuration file. Supported sections:
| Section | Purpose |
|---|---|
[MITM] |
Add hostnames to MITM decryption list |
[Script] |
Register JavaScript scripts |
[URL Rewrite] |
Add URL rewrite rules |
[Header Rewrite] |
Add header rewrite rules |
[Rule] |
Add routing rules |
[Host] |
Add DNS host-to-IP mappings |
For compatibility, a
[DNS]section in a module is accepted as an alias of[Host].
Module Metadata
Modules can include metadata directives (lines starting with #!):
#!name = My Custom Module
#!desc = Blocks ads and trackers for example.com
#!system = ios,macos
| Directive | Description |
|---|---|
#!name |
Module name (displayed in UI) |
#!desc |
Module description |
#!system |
Platform filter: ios, macos (comma-separated) |
#!arguments |
Declares module variables with default values (e.g. #!arguments = var1:default1, var2:default2) |
#!system is informational metadata shown in the module editor; it does not currently gate loading — the module is applied on all platforms.
#!arguments may appear multiple times; later declarations override earlier ones. {{{variable}}} placeholders in the module body are replaced with the resolved value: an app-provided override wins, then the #!arguments default, then the empty string.
Module Example
#!name = Ad Block Module
#!desc = Block common ad domains
#!system = ios,macos
[Rule]
DOMAIN-SUFFIX,doubleclick.net,REJECT
DOMAIN-SUFFIX,googlesyndication.com,REJECT
DOMAIN-SUFFIX,googleadservices.com,REJECT
[Host]
localhost = 127.0.0.1
[MITM]
hostname = *.google-analytics.com
[URL Rewrite]
^https://example\.com/old-api https://example.com/new-api 302
%APPEND%/%INSERT%directives inside a module'shostnamevalue are stripped and the hostnames merged into the MitM list; a leading-exclusion prefix on a hostname is preserved.
Module Lifecycle
- Modules are loaded after the main configuration is parsed.
- Rules, scripts, MitM hosts, and DNS hosts from modules are added to the runtime managers.
- When a module is removed or disabled, all its rules, scripts, and hosts are unregistered.
- Remote module content is fetched when the tunnel starts, and re-fetched only when the
[Module]URL list changes on a configuration reload.