Subscriptions and data

ClashPulse never edits a source profile. It keeps a private last-known-good snapshot of each subscription and adds filters, data resources, and DNS routes in the generated Mihomo config.

Subscriptions

Add one in the GUI, with TUI Subscriptions n, or in subscriptions.toml:

[[subscription]]
id = "primary"                   # Stable ASCII ID; do not reuse it.
name = "Primary"                  # Safe display name.
url = "https://provider.example/profile?token=replace-me"
enabled = true
refresh_interval = "12h"
route = "auto"

HTTPS is required unless the subscription sets allow_http; allow_invalid_tls is the other per-subscription exception. URLs with user:password@ are rejected. Up to 5 redirects are followed, each checked the same way. Validators and a custom user_agent (printable ASCII, at most 256 bytes, default clash-pulse) go only to the original origin. timeout covers download, render, and validation.

Download (clashpulse download subscription [id]) stores an inactive snapshot without touching Mihomo. Refresh (GUI Refresh, TUI r, clashpulse refresh) also renders the full config and validates it with Mihomo, but does not switch. Activate (GUI Activate, TUI a) validates and applies it as one transaction.

A failure leaves the active config and previous snapshot alone. An unchanged 304 or a body with the stored hash replaces nothing. A profile without proxies or proxy-providers is a failure too; providers often send one for an expired account.

route connection
auto (default) through the running Mihomo; while it is stopped, terminal commands honor http_proxy, https_proxy, and no_proxy, and the desktop service connects directly
direct direct, ignoring proxy variables
system_proxy the OS proxy; fails when none is set
mihomo_proxy Mihomo’s mixed port; fails while Mihomo is stopped

An unavailable route is an error, never a fallback. Data resources always use auto. Refresh short-lived provider URLs before they expire.

Data resources

New configs enable four MetaCubeX/meta-rules-dat sources in resources.toml:

id kind format
geoip geoip.dat dat
geosite geosite.dat dat
country Country.mmdb mmdb
cn rule-set (domain) mrs

cn routes nothing until a filter or DNS route uses it.

Resources download on refresh or activation, or with clashpulse refresh resource [id], which also works without an active profile. With a profile active, Mihomo stops before the files change and restarts after validation; a failed update restores the old files.

The default releases/download/latest URLs move and have no SHA-256 pin. For a fixed digest, use a versioned asset. Licensing is in dependencies.

Filter lists

A filter routes a rule-set resource to a proxy or group of the active profile:

[[filter]]
id = "domestic-filter"
resource = "cn"   # Stable ID of an enabled rule-set or rule-provider resource.
format = "mrs"    # Must match the referenced resource format.
target = "Proxy"  # A proxy or group in the active profile, or DIRECT/REJECT.
enabled = true

Managed RULE-SET rules go before the profile’s own rules. An unknown target fails the render.

DNS routing

The DNS listener defaults to 127.0.0.1:1053 ([dns] listen) and must be loopback. Routes map a matcher to a resolver set and become Mihomo’s nameserver-policy (GUI Settings > DNS, TUI Settings v and a):

[[resolver_set]]
id = "domestic"
endpoints = ["https://dns.example/dns-query"]

[[dns_route]]
resource = "cn"   # Alternatively suffix = "example.cn" or geosite = "cn".
resolver_set = "domestic"

Each route has exactly one of suffix, geosite, or resource. An endpoint that loops back to the listener is a load error.

ClashPulse does not run DNSCrypt. Run dnscrypt-proxy on loopback UDP or TCP and mark the resolver set:

[[resolver_set]]
id = "domestic"
endpoints = ["udp://127.0.0.1:5353"]
dnscrypt = true   # Requires a reachable loopback UDP/TCP DNSCrypt listener.

On every render ClashPulse queries each DNSCrypt endpoint with a 2 second timeout. If one does not answer, the change fails and the running config stays.