Gemini-Config-Checker- README

README проекта с github.com/WireProvostPucker/Gemini-Config-Checker-. Одним файлом markdown: README.md.

Gemini/Check

English · فارسی

Download the Gemini app

Gemini Config Checker

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.

Two modes, one switch

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)

Contents

Credits · Why a signed-in browser · Download and install · User guide · Troubleshooting · Privacy and security · Build from source · Releases and CI

Credits and references

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)

Why a signed-in browser?

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"

Download and install

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
Windows
  1. Download gemini-config-checker-desktop_<version>_windows_amd64.zip (or arm64) and unzip it anywhere.
  2. Run GeminiConfigChecker.exe. WebView2 is built into Windows 10/11; if SmartScreen warns, choose More info → Run anyway (the build is unsigned).
macOS
  1. Download ..._macos_universal.zip, unzip, and move the .app to Applications.
  2. First launch: right-click the app → Open. If macOS still refuses: xattr -dr com.apple.quarantine "/Applications/GeminiConfigChecker.app".
Linux
  1. Install the runtime libraries once: sudo apt install libgtk-3-0 libwebkit2gtk-4.1-0 (Debian/Ubuntu; use your distribution's equivalents).
  2. tar -xzf gemini-config-checker-desktop_<version>_linux_amd64.tar.gz, then run ./GeminiConfigChecker.
  3. No desktop environment? Use the web server build instead: ./gemini-config-checker and open http://localhost:8787.
Android
  1. Download gemini-config-checker_<version>_android_arm64.apk on the phone.
  2. Allow Install unknown apps for your browser or file manager, then open the APK.
  3. Launch the app. A persistent notification ("Scanner engine is running") is expected: the engine runs as a foreground service so long scans survive the screen turning off. Use its Stop action to quit the engine.
  4. The APK runs the connectivity-only mode (see Settings reference). Android does not let apps drive a signed-in Chromium, so the region cannot be verified there.
  5. The release APK is signed with the repository key when one is configured, otherwise with a throw-away key: it installs, but a later build cannot update it in place, so uninstall first.
Web server (any OS, servers, Termux)

./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.

User guide

1. First start

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).

2. Pick a mode

3. Sign in with Google (region check)

The region check opens AI Studio and Gemini as you. Click Sign in with Google once:

  1. A Chrome / Edge / Brave window opens in a separate profile that only this app uses. Sign in normally. The app never sees your password.
  2. When sign-in is detected the window closes by itself and the card turns to "Google account connected". The sign-in is remembered for next time.
  3. Prefer a secondary account: requests come from many IPs, so Google may show a "suspicious sign-in" notice.
  4. Remove account from app deletes only that private profile. It never touches your everyday browser or accounts.

No browser installed, or on Android? Switch the check type (Settings) to connectivity only: no sign-in or browser needed.

4. Simple mode, step by step

  1. Paste your configs into the box, one per line: 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).
  2. Keep Anti-DPI on if you are inside a network where plain Cloudflare configs do not connect (see section 6).
  3. Sign in (region check) or choose connectivity only.
  4. Press Start scan (or Ctrl+Enter). Watch the Results tab fill in.

5. Advanced mode, step by step

  1. Base config: a config that works for you and does not get the region wall on AI Studio. Paste a share link, or a full xray JSON, even a multi-hop chain (for example an exit that already dials through a Cloudflare worker). This is the route every free config will be chained behind.
  2. Anti-DPI: applied to the base config's first hop, the connection that leaves your machine.
  3. Source: choose a ready-made list (verified is recommended) or paste free configs yourself. custom accepts any subscription URL.
  4. Settings, sign-in, Start scan. Before testing the free configs, the app tests your base config first and stops with a clear message if the base itself cannot reach Google.

6. The anti-DPI profile

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)

7. Settings reference

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

8. Reading the results

9. Using what you found

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.

10. Android notes

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.

Troubleshooting and FAQ

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).

Privacy and security

Details and reporting: SECURITY.md.

Build from source

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

Releases and CI

Project layout

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

Disclaimer

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.

License

MIT. The bundled engine (Xray-core) and fonts keep their own licenses (MPL-2.0 and SIL OFL).

Gemini-Config-Checker- (WireProvostPucker/Gemini-Config-Checker-)

Ищем в базе…

Что это?Инструмент, который проверяет прокси-конфиги: открываются ли Google AI Studio и Gemini на самом деле. Проверка идёт через браузер с выполненным входом в аккаунт и по тому же маршруту, которым вы реально пользуетесь.
Это десктопное приложение или веб-сервис?Оба варианта. Есть нативное десктопное приложение для Windows, macOS и Linux, а также APK для Android. Его можно также запустить как локальный веб-сервер, и интерфейс откроется в браузере.
Как это запустить?Скачайте сборку для своей системы на странице Releases. В Windows распакуйте архив и запустите GeminiConfigChecker.exe. WebView2 встроен в Windows 10 и 11, поэтому там ничего дополнительно устанавливать не нужно.
Нужно ли сначала установить браузер?Для проверки региона — да: нужен Chrome, Edge или Brave. Режиму только проверки связи не нужны ни браузер, ни вход в аккаунт.
Все ли платформы одинаково протестированы?Пока нет. Полный сквозной прогон выполнен только в Windows. Сборки для macOS, Linux и Android собираются через CI и на реальных устройствах не проверялись.
Где хранятся мои данные?Конфиги и настройки хранятся только на этом устройстве, в локальном хранилище приложения, и только если отмечена опция «запомнить».
Зачем использовать браузер с входом в аккаунт, а не простую проверку через API?Google определяет доступ к региону для каждого аккаунта уже после загрузки страницы, а обычные HTTP-запросы отвечают «всё в порядке» из любой страны. Только проверка с входом в аккаунт показывает, что увидел бы реальный пользователь.
Что нужно режиму «Advanced» перед запуском?Одну рабочую базовую конфигурацию, которая не упирается в региональную блокировку AI Studio. Приложение сначала проверяет базу и останавливается с понятным сообщением, если не может достучаться до Google.
Можно ли пользоваться этим на Android?Да, как APK в режиме только проверки связи. Android не позволяет приложениям управлять Chromium с входом в аккаунт, поэтому регион там проверить нельзя.
Откуда взят рецепт против DPI?Он следует рецепту от patterniha для клиента PattN. Локальный фрагментирующий форвардер приложения воспроизводит семантику фрагментации из его форка Xray-core.
Размер
0.2 MB
Звёзды
473
Обновлён
КоммитNov 15
Возраст
3 д
Коммиты · 90 дней