The project's README from github.com/TrooperFilter/Gemini-Config-Checker-. As one markdown file: README.md.

English · فارسی
Find proxy configs that actually get you into Google AI Studio and Gemini, by testing each one the way a person would: in a signed-in browser, through the route you will really use.
Version 0.1.0, early pre-release. It works end to end on Windows (the only platform it has been run on so far). The macOS, Linux and Android builds come from the CI pipeline and have not been exercised on real devices yet. Please report what you find.
The big Simple / Advanced switch in the header decides what is tested. The route diagram under the title morphs to show it.
| Simple | Advanced | |
|---|---|---|
| Question it answers | Which of my configs work? | Which free configs work through my config? |
| Route | you → config → AI Studio / Gemini | you → base config → free config → AI Studio / Gemini |
| You provide | your configs (links, a subscription URL or base64), or pick a ready-made free list | one working base config, plus a free list or pasted configs |
| Anti-DPI profile is applied to | every config under test (each one connects from your machine) | the base config's first hop (free configs run inside its tunnel) |
| Typical use | check a pile of configs you already have; test a config before you rely on it | your Cloudflare config works, but you need a different exit that Google accepts |
| Export | links, base64, a full Xray config of one config | links, base64, a chain Xray config (base → free) |
Credits · Why a signed-in browser · Download and install · User guide · Troubleshooting · Privacy and security · Build from source · Releases and CI
This project exists because of other people's work. Please go and use and star them.
| Project | What it gave us |
|---|---|
| 0xRadikal/Free-v2ray-Configs | The auto-updated lists of free configs (verified, fast, secure, ...) that this tool scans |
| patterniha | PattN (Windows / Linux / macOS client) and PattNG (Android): the anti-DPI recipe, plus the fragment finalmask semantics from his Xray-core fork that our fragmenting forwarder reproduces |
| bia-pain-bache/BPB-Worker-Panel | The Cloudflare Worker panel that produces many of the base configs this tool chains behind (patterniha maintains a fork) |
| Anti-DPI recipe post | The exact Finalmask / fingerprint / ALPN / cipher values used as defaults |
| MatinSenPai/SenPaiScanner | Companion tool for finding clean Cloudflare IPs to use as a config's address |
| XTLS/Xray-core | The proxy engine embedded in the app |
| 2dust/v2rayN | The config layout the "Copy with chain" export follows (PattN is a fork of it) |
| Wails | The native desktop shell |
| Vazirmatn and JetBrains Mono | The fonts used in the UI (SIL Open Font License) |
Google decides region availability per signed-in account, after the page has loaded. A plain HTTP request (even to the Gemini API with a dummy key) answers "fine" from every country, so connectivity probes mark every live config as healthy. Measured while building this tool: exits geolocated to the US, HK and SG were blocked, and the same exit can flip over time. The only reliable signal is what Google shows a signed-in user, so that is what this tool reads:
| Product | "Blocked" looks like |
|---|---|
| AI Studio | redirect to /docs/available-regions |
| Gemini | "Gemini isn't currently supported in your country" |
Get the build for your system from the Releases page. Every release ships SHA256SUMS.txt.
| Platform | Desktop app (native window) | Web server (UI in your browser) | Region check |
|---|---|---|---|
| Windows | amd64, arm64 | amd64, arm64 | ✅ needs Chrome / Edge / Brave |
| macOS | universal (Intel + Apple Silicon) | amd64, arm64 | ✅ needs Chrome / Edge / Brave |
| Linux | amd64 (GTK 3 + WebKitGTK 4.1) | amd64, arm64, armv7 | ✅ needs Chrome / Chromium / Edge / Brave |
| Android 8+ | APK (arm64-v8a) | build from source for Termux (GOOS=android) |
❌ connectivity mode only |
gemini-config-checker-desktop_<version>_windows_amd64.zip (or arm64) and unzip it anywhere.GeminiConfigChecker.exe. WebView2 is built into Windows 10/11; if SmartScreen warns, choose More info → Run anyway (the build is unsigned)...._macos_universal.zip, unzip, and move the .app to Applications.xattr -dr com.apple.quarantine "/Applications/GeminiConfigChecker.app".sudo apt install libgtk-3-0 libwebkit2gtk-4.1-0 (Debian/Ubuntu; use your distribution's equivalents).tar -xzf gemini-config-checker-desktop_<version>_linux_amd64.tar.gz, then run ./GeminiConfigChecker../gemini-config-checker and open http://localhost:8787.gemini-config-checker_<version>_android_arm64.apk on the phone../gemini-config-checker serves the same UI on http://localhost:8787 and opens your browser. Flags: -addr 127.0.0.1:8787, -no-open, -version.
The UI has no authentication: keep it on localhost, or tunnel it (ssh -L 8787:localhost:8787 your-server) instead of exposing it.
The window has three tabs: Scan (what to test and how), Results (live list, filters, copy buttons) and Export. The header holds the Simple / Advanced switch, the scan status, and a light/dark theme button. Everything you type is remembered on this device when "remember" is ticked (untick it on a shared computer).
The region check opens AI Studio and Gemini as you. Click Sign in with Google once:
No browser installed, or on Android? Switch the check type (Settings) to connectivity only: no sign-in or browser needed.
vless://, vmess://, trojan://, ss://. A subscription URL (https://…) or base64 text also works.
Leave the box empty to test a ready-made free list instead (pick one below).Ctrl+Enter). Watch the Results tab fill in.verified is recommended) or paste free configs yourself. custom accepts any subscription URL.Inside Iran, plain Cloudflare configs mostly connect only with the settings below (recipe by patterniha / PattN). The values can change, so every one is editable; Suggested values restores the defaults.
| Setting | Default | What it does |
|---|---|---|
| Finalmask (JSON) | two fragment masks: tlshello with lengths [0,104,1], then 1-1 with lengths [114,1] |
splits the TLS ClientHello so filters cannot read the server name |
| Fingerprint | unsafe |
native Go TLS instead of a browser imitation, so the cipher list below applies |
| ALPN | http/1.1 |
|
| Cipher suites | the 13-suite list from the recipe | |
| Clean IP | empty | replaces the connection address (the old domain stays as SNI and Host) |
finalmask, cipherSuites, alpn in JSON, or fm, ciphers, alpn, fp link parameters), this button copies them into the form.length/delay per fragment mask, while the recipe uses per-segment lengths/delays (a PattN fork feature). The app runs the same
fragmenting algorithm in a small local forwarder in front of the connection. Only fragment masks are supported; other mask types are rejected with a clear message.| Setting | Default | Meaning |
|---|---|---|
| Check type | Region with signed-in browser | Region: opens AI Studio and Gemini and reads Google's verdict (accurate, 20–40 s per config). Connectivity only: just proves the route reaches Google and measures latency (fast, no sign-in, but the region is not checked) |
| "Healthy" means | AI Studio and Gemini | Require both, only AI Studio, or only Gemini |
| Max configs | 60 | How many configs to test (the list is shuffled first) |
| Simultaneous browser checks | 4 | Each uses about 200 MB of RAM; lower it on small machines |
| Simultaneous connectivity tests | 20 | The cheap first stage that drops dead configs before the browser stage |
| Connectivity timeout | 10 s | Raise it on slow links |
| Remember | on | Stores configs and settings in the app's local storage on this device only |
✓ free, ✗ blocked)..json file. Choose the target client:| Target | Option | finalmask in the file |
|---|---|---|
| PattN / PattNG | PattN / PattNG (with finalmask) | included |
| Xray / v2rayN with the stock core | Xray / v2rayN standard | removed (stock cores cannot parse the fork's schema) |
The file uses the classic vnext / servers layout (old and new cores accept it), mixed inbounds on 10808 and 10809, pinned DNS and a UDP/443 block.
In v2rayN: Servers → Add custom configuration server and pick the file. To try it without a GUI: xray run -c file.json.
Same UI, connectivity mode only, default Simple. The foreground notification keeps the engine alive during a scan; tapping it reopens the app, Stop shuts the engine down. "Save to file" opens Android's file picker.
| Symptom | What to do |
|---|---|
| "No Chrome / Edge / Brave found" | Install one, or choose connectivity only. Searched: Windows Program Files / per-user installs / the registry "App Paths" (Chrome, Edge, Brave, Chromium, Vivaldi, Opera); macOS /Applications, ~/Applications and Spotlight; Linux PATH, /usr/bin, /snap/bin, /opt/.... A browser somewhere else: set GCC_BROWSER (or CHROME_BIN) to its executable. Flatpak browsers cannot be driven. |
| Linux: sign-in window does not open | The window needs a graphical session (DISPLAY / WAYLAND_DISPLAY); on a server, sign in on a desktop. Snap browsers work (the profile is kept under ~/snap/<browser>/common); as root the browser starts with --no-sandbox. |
| "Google session expired, sign in again" | Press Sign in with Google again. A sign-in redirect must persist for several seconds before the app believes it, so a brief redirect no longer aborts a scan; if it still happens, Google really asked you to sign in again (often a security check after many IPs). |
| Everything times out | The base config (advanced) or the configs themselves (simple) cannot connect. Inside a filtered network turn the anti-DPI profile on and try a clean IP; make sure the base config works in your normal client. |
| AI Studio passes but Gemini is blocked (or the reverse) | They use different region rules. Change "Healthy" means if you only need one. |
| A config passed, then failed later | See "A verdict is a sample": the exit varies per connection. Re-test before relying on it. |
| "A scan is already running" | Stop it first (the red button in the bar or in Results). |
| Windows SmartScreen / macOS Gatekeeper warns | The builds are unsigned. Use Run anyway / right-click → Open (see Download). |
| Linux: window does not open | Install libgtk-3-0 and libwebkit2gtk-4.1-0, or use the web server build. |
| Android: install blocked | Allow "Install unknown apps" for the app you used to open the APK. |
| Android: "App not installed as package appears to be invalid" | The file is damaged or incomplete (a half-finished download, or a repository page saved as .apk). Download it again, check its size and SHA256SUMS.txt, or install it from a computer with adb install file.apk. It also appears when an APK signed with a different key is installed over an older build: uninstall the old app first. |
| Start over completely | Remove account from app, then delete the app's local storage (Windows: %AppData%\GeminiConfigChecker; macOS: ~/Library/Application Support/GeminiConfigChecker; Linux: ~/.config/GeminiConfigChecker). |
127.0.0.1 and rejects foreign Host headers and non-JSON POSTs, but it has no authentication.Details and reporting: SECURITY.md.
Requires Go (see go.mod). The desktop app additionally needs Wails v2 and the platform webview
(WebView2 on Windows, WebKit on macOS, GTK 3 + WebKitGTK 4.1 on Linux). The Android app needs the Android SDK, JDK 17+ and Gradle 8.10.
make test # vet + unit tests
make web # ./dist/gemini-config-checker
make desktop # native app via Wails (on the target OS)
make android # APK (engine for arm64 + Gradle)
make dist VERSION=0.1.0 # cross-compiled web binaries for all targets
ci.yml: gofmt, vet and tests on Linux / Windows / macOS; cross-compile check for every web target.release.yml: builds desktop apps (Windows amd64/arm64, macOS universal, Linux amd64), web servers (Linux, Windows, macOS) and the Android APK, writes SHA256SUMS.txt
and publishes the GitHub release v<VERSION>. It runs by itself only when a push to main changes VERSION (ordinary pushes run just ci.yml): if that release does not exist yet it is
built and published, otherwise the run does nothing. To ship a new version, bump VERSION and CHANGELOG.md and push. A tag vX.Y.Z matching VERSION, or
Actions → Release → Run workflow (tick "publish", also how you retry a failed release), works too.ANDROID_KEYSTORE_BASE64, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS, ANDROID_KEY_PASSWORD.main.go web server (HTTP API + embedded UI)
desktop/ Wails desktop shell around the same engine and UI
android/ Android app: foreground service + WebView around the same engine
internal/scan/ engine: config parsing, anti-DPI forwarder, chain builder, browser region check
internal/ui/ single-page UI and fonts (shared by every build)
internal/buildinfo/ version stamped at release time
VERSION the version the release workflow publishes
This tool measures connectivity and regional availability. Use it in accordance with the laws of your country and the terms of the services you access. Free configs are run by unknown third parties; do not send sensitive data through them.
MIT. The bundled engine (Xray-core) and fonts keep their own licenses (MPL-2.0 and SIL OFL).