🧹 sub-filter

Smart proxy subscription filter
VLESS · VMess · Trojan · Shadowsocks · Hysteria2

Removes junk. Keeps only secure servers.

---

sub-filter is an intelligent proxy subscription filter for VLESS, VMess, Trojan, Shadowsocks, and Hysteria2.
It automatically:

• 🔒 Blocks insecure configurations (e.g., VLESS without encryption)
• 🧪 Validates correctness (required parameters, allowed values)
• 🚫 Rule-based filtering of prohibited (bad) keywords
• 🌍 Selects servers by country (flag, name, ISO code)
• 🔁 Merges and deduplicates multiple subscriptions into one clean list

The result is a ready-to-use subscription for Clash, Sing-Box, routers, and other clients.

⚠️ Note: This tool does not test proxy liveness (availability/latency).
For that, use xray-checker.

---

📚 Documentation

Topic	Links
Main Guide	EN · RU · ZH
FAQ	EN · RU · ZH
Validation Rules	EN · RU · ZH
Bad words filters	EN · RU · ZH
Configuration	config/config.yaml
Rules Example	config/rules.yaml
Bad words Example	config/badwords.yaml
Example configuration	./config
for developers:
Extending	EN · RU · ZH
Error Types	EN · RU · ZH

---

🚀 Quick Start

# Start server on port 8000
./sub-filter 8000

# Test output
curl -H "User-Agent: Clash" "http://localhost:8000/filter?id=1&c=RU"

# Process subscriptions in CLI mode and print to terminal
./sub-filter --cli --stdout --country=NL,RU

💡 Don’t forget to review the configuration files!

---

🐳 Docker

docker run -d \
  -p 8080:8080 \
  -v $(pwd)/config:/config:ro \
  -v $(pwd)/cache:/tmp/sub-filter-cache \
  ghcr.io/viktor45/sub-filter:latest \
  8080

---

💡 Tip: Use sub-filter as a middleware between public subscriptions and your client — and forget about broken or misconfigured proxies!

Star History