FLAT447/v2ray-lists: a self-updating feed of free VPN and MTProxy configs

What the project actually does

FLAT447/v2ray-lists is a collection of free VPN configurations and MTProxy lists, maintained as a GitHub repository. The README describes it as a source for V2Ray, VLESS, VMess, ShadowSocks, Trojan, TUIC, Hysteria2, and Reality configs, plus MTProxy for Telegram. The project does not host servers. It aggregates, checks, and republishes configurations that are already available elsewhere, and it does this on a schedule. The intended user is someone who wants a ready-made subscription URL to import into a VPN client like v2rayNG, without manually hunting for working servers. The repository also provides QR codes for the configs, which makes it practical for Android TV or other devices where typing a long URI is painful. The core problem it solves is the churn of free proxy lists: servers die, get blocked, or become slow, and this project tries to keep a usable set alive.

How the generator and checker work

The repository layout shows a Python-based generator under sources/. There are two scripts: vpn_checker.py and proxy_checker.py. The README's local run instructions mention vpn_checker.py for generating the four subscription files (WHITE_FULL, BLACK_FULL, WHITE_LITE, BLACK_LTE) and proxy_checker.py for the MTProxy whitelist.txt and blacklist.txt files. The naming suggests a distinction between 'white lists' and 'black lists', which likely refers to the type of network restrictions they are designed to bypass, though the README does not define the terms. The generator runs inside a GitHub Actions workflow that the README says updates every 9 minutes. That frequency is aggressive for a free service, and it implies the checker is lightweight, probably just pinging endpoints or testing TCP connectivity. The output files are plain text subscription lists, and the qr-codes/ directory contains PNG versions for each generated list. The structure is simple: sources for the scripts, generated artifacts at the root, and a static site under flat447.github.io for the MTProxy random picker.

Getting it running locally

The README gives explicit commands for local execution. You clone the repository, move into sources/, install dependencies with python -m pip install -r requirements.txt, and then set a GITHUB_TOKEN environment variable with repo permission, because the scripts push changes back to the repository. After that you run python vpn_checker.py and python proxy_checker.py. The token requirement is a notable detail: the checker is designed to write results back to GitHub, not just print them to stdout. That means a local run is not a read-only operation unless you modify the scripts. The README also lists a requirements.txt, but it does not enumerate the packages. The actual filenames in the repository are vpn_checker.py and proxy_checker.py, while the local run section shows vpn_checker.py, so there is a minor inconsistency in the documentation. The generated files are stored in a githubmirror/ directory according to the structure, which contains 26 .txt files, but the main subscription links point to the root-level files like WHITE_FULL.txt. Users who only want the configs do not need to run anything; they just copy the raw GitHub URLs into their client.

The subscription files and their practical use

The main deliverables are four subscription files: WHITE_FULL, WHITE_LITE, BLACK_FULL, and BLACK_LTE. The README warns not to copy links from the status table, because that table only lists sources. The actual subscription links are in the 'Основные подписки' section. For MTProxy, the README directs users to a website that picks 10 random proxies from the whitelist, then asks them to import the clipboard into Telegram on mobile or desktop. For VPN configs, the workflow is: copy the subscription URL, import it into v2rayNG, run a latency test, sort by result, and pick the best server. This is a practical pattern for users who do not want to manage individual servers. The QR codes are an alternative for Android TV, where the import path is different. The README's guides are specific to v2rayNG, which suggests the project is tested primarily with that client. There is no mention of support for iOS or desktop clients beyond the generic import steps.

What the project does not tell you

The README is thin on several points that matter for adoption. It does not explain where the source configs come from, how the checker validates a server, or what criteria distinguish a 'white' from a 'black' list. The status table lists files with descriptions like 'Подписка для Чёрных Списков' and 'Подписка для Белых Списков', but the meaning is left to inference. There is no information about encryption, authentication, or whether the configs are original or scraped from other public lists. The license is GPL-3.0, which is fine for a generator, but the generated configs themselves are data, not code, and the license does not clarify whether the proxy links are subject to any separate terms. The README also does not mention any rate limits, uptime guarantees, or a mechanism for users to report dead servers. The 9-minute update cycle is stated, but there is no evidence of how reliable that schedule is in practice, since no release history or commit data was retrieved.

Security and trust considerations

Using free VPN configs from an unknown third party is inherently risky. The repository provides no attestation about the operators of the servers behind the configs. A malicious server could log traffic, inject data, or perform TLS interception if the client trusts the proxy's certificate. The README does not address this at all. The project's value depends on the assumption that the sources are benign, but there is no way to verify that from the repository alone. The MTProxy lists are especially concerning because they are meant for Telegram, where users might expect encryption, but MTProxy is a protocol that can be monitored by the proxy operator. The README's instructions to pick 10 random proxies from the whitelist suggest that the author is aware of the unreliability, but randomness does not equal safety. For anyone who needs privacy, a commercial VPN with a published privacy policy is a safer choice. This project is a convenience layer, not a security product.

Alternatives and the difference in approach

A direct alternative is a service like v2rayShare or free-vpn-servers lists, which also aggregate free configs but often rely on manual curation or user submissions. The key difference is that FLAT447/v2ray-lists automates the checking and republishing process through GitHub Actions, which means the lists are refreshed without human intervention every 9 minutes. Another alternative is to run your own server with a tool like Xray or V2Ray, which gives you full control but requires a VPS and maintenance. The trade-off is clear: this project offers zero cost and zero setup, but also zero control over the endpoints. A more robust alternative for a team would be to use a commercial proxy service with an API, where you can rotate credentials and get support. For a single user who wants a quick way to bypass censorship, this repository is a reasonable starting point, but it should not be the only tool in the box.

Maintenance and upgrade cost

The project's maintenance burden is low for users, because the GitHub Actions workflow handles updates automatically. For someone who wants to run the generator locally, the cost is higher: you need to install Python dependencies, set up a GITHUB_TOKEN, and run two scripts. The scripts are not versioned with releases, so there is no clear upgrade path. The README does not mention any changelog or migration notes. The repository is not archived, and the last push date is unknown, so it is unclear whether the project is actively maintained. The 9-minute update cycle, if it works, means the subscription files are always fresh, but that also means the repository is constantly changing, which could break clients that cache subscriptions. The GPL-3.0 license means any derivative work that you distribute must also be GPL-3.0, but for personal use this is irrelevant. The practical cost is the time to verify each config before trusting it, and that cost is repeated every time the list changes.

Editorial conclusion

Adopt this project if you need a free, regularly updated source of VPN and MTProxy configs for personal testing or for a project that can tolerate unstable endpoints. Do not use it for production traffic or for anything requiring guaranteed uptime, because the configs come from unknown third parties and the repository does not provide any trust metadata. Before relying on any subscription, verify the checksums or contents of the files yourself, test each server's latency and throughput in your own client, and review the GPL-3.0 license if you plan to redistribute or modify the generated lists. The project is a generator and a curation layer, not a VPN service, and its value depends entirely on the quality of the upstream sources it checks.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository