proxy-god/README.md

Proxy God

Multi-hop proxy chains. Self-healing. Windows-native. You pick the exit; the machine enforces the rules.

Not another toy script. This is a full rotating chain engine on top of GOST: it pulls lists, stress-tests proxies in parallel, builds random hops, and keeps checking until something dies—then it rotates and keeps going. Optional firewall kill-switch so traffic either goes through your chain or it doesn’t go out at all (when you run as Admin). Works under NordVPN (or any VPN) so your outer tunnel stays first—then the chaos of public proxies happens inside that envelope.

YOU → VPN (outer tunnel) → Hop 1 → Hop 2 → … → Last hop → Internet

---

What it does (the short version)

Layer	What happens
Pool	Fetches live lists (Proxifly CDN), dedupes, validates like a hammer.
Chain	Random N-hop path through survivors—no lazy repeats in a cycle.
Exit check	If your “exit IP” looks like your real IP, the chain is dead—rotate.
System proxy	WinINet gets the rules—apps that respect Windows proxy follow the chain.
Kill-switch	Optional netsh lockdown: GOST, this app, NordVPN stack get out; everything else can wait (Admin).
Tray	Green / yellow / red. You know the state without opening the window.
Boot	Scheduled task—fire on logon, keep the machine in the game.

---

Firepower (features)

• Auto pool — Pull, validate, shuffle, drain. Rinse on a timer.
• 1–8 hops — Slider + top-bar +/−. You control depth.
• Obfuscation modes — Auto, HTTP-only, SOCKS5-only, Random Mix.
• Fixed exit — Last hop only: yours. Everything else still rotates. Hop count 1 = only your exit, no pool.
• Pinned chain — Full manual order when you want to own the path.
• Leak sniffing — Compares exit IP vs direct; mismatch or no exit = rotate.
• GOST — Downloaded once; Defender exclusion on the app folder so AV doesn’t eat the binary.
• VM-safe — Listener stays on 127.0.0.1—clone the box, DHCP can change; this doesn’t care.

---

Requirements

• Windows 10/11 x64
• Python 3.10+ on PATH (or the py launcher with a 3.10+ install) — only needed to build; the shipped .exe runs without Python
• VPN recommended (Nord or any)—outer tunnel before the proxy zoo

---

Clone / pull → one build script → Desktop

Typical flow:

1. Clone (or git pull if you already have the repo):

   git clone https://gitea.thetempleofdoom.com/drjones/proxy-god.git
   cd proxy-god
   

2. Python (first machine only): if python --version / py -3 isn’t 3.10+, install then reopen the terminal:

   winget install Python.Python.3.12 --accept-package-agreements --accept-source-agreements
   

3. Build — upgrades pip, installs requirements.txt + PyInstaller, produces dist\ProxyChainManager.exe, copies ProxyChainManager.exe to your Desktop, and creates Proxy God.lnk pointing at it:

   powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup_and_build.ps1
   

   Same steps from build_exe.bat or double‑click FirstRun_Build_And_Install.bat (checks Python 3.10+, then runs the same script; pauses at the end so you can read errors).

Where	What
dist\ProxyChainManager.exe	Built app (same bits as Desktop copy)
Desktop → Proxy God.lnk	Double‑click this — shortcut to the Desktop exe
Desktop → ProxyChainManager.exe	Same app (refreshed every build)

After a successful build, if the shortcut is missing but the exe exists, you can recreate it:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\create_desktop_shortcut.ps1

First run of the exe: accept UAC if you want the firewall kill-switch. In the app, press ▶ Start.

You do not need Python installed to run the Desktop .exe — only to build it with the script above.

---

Quick start (run from source, no exe)

cd proxy-god
pip install -r requirements.txt
python run.py

Administrator = full kill-switch. No admin = still runs; firewall enforcement steps aside.

Self-test (core logic, no GUI)

python -m unittest discover -s tests -v

Hits config sanitization, fetcher smoke, validator timeouts, and a live get_direct_ip check (skips if you’re offline).

---

Run it like you mean it

1. Launch Proxy God.lnk on the Desktop (or ProxyChainManager.exe) — UAC if you want the kill-switch.
2. Tweak Settings if you’re picky—defaults are solid out of the box.
3. Hit Start. First run grabs GOST, whitelists the folder in Defender, pulls lists, validates, chains, verifies exit IP, sets system proxy, engages firewall (if Admin).
4. Close the window → tray; the engine keeps running until you Quit.

---

Chain Builder (where you get surgical)

• Mode — Protocol mix for the pool.
• Hops — Total length; fixed exit always rides last (unless you pinned a full manual chain).
• Manual list — Add, reorder, pin when you don’t trust randomness.
• Sources — Your JSON URLs; defaults are Proxifly CDN endpoints.

---

Settings cheat sheet

Setting	Default	Meaning
Local port	18888	Where your HTTP proxy listens
Health check	180 s	How often the exit gets re-proven
Pool refresh	1800 s	How often lists get re-fetched and re-tested
Concurrency	64	How hard you spam validation
Stop after N valid	20	Early-exit — stop testing as soon as N good proxies found
Max candidates	200	Cap per cycle (shuffled, so random sample)
Timeout	12 s	Per-proxy patience
Kill-switch	ON	All-or-nothing outbound (when Admin + firewall engaged)

---

Stack (for people who read code)

app.py          Dark UI — CustomTkinter, tabs, tray
service.py      Async loop — pool, GOST, health, rotation
gost_util.py    GOST binary + Defender hook
firewall.py     netsh kill-switch
sysproxy.py     Registry + WinINet broadcast
tray.py         Status icon
validator.py    httpx + SOCKS — parallel checks
fetcher.py      Proxifly JSON
config.py       Settings + sanitization

---

Default sources

Proxifly / free-proxy-list over jsDelivr—HTTP, SOCKS5, HTTPS JSON feeds. Roll your own: any URL that returns [{"proxy":"http://ip:port",...}, ...].

---

Reality check (read this)

• Public proxies are hostile—treat them as disposable. No banking over cleartext.
• VPN first means proxy operators see the VPN exit, not your home ISP.
• Kill-switch is serious—it can block apps that don’t play by proxy rules. Know what you’re doing.
• Clone-friendly: bind is loopback—this repo doesn’t bake in LAN IPs.

---

Proxy God — not because it’s polite. Because it runs.