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 |
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) |
If #!system is specified and the current platform doesn't match, the module is silently skipped.
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
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 modules are re-fetched according to the main configuration's managed config update interval.