V2RayAggregator: A GitHub Actions Pipeline That Collects and Speed-Tests Free Proxy Nodes

What V2RayAggregator Actually Solves

Free proxy nodes circulate through Telegram channels, blogs and public subscription pages, and the same node reappears under a dozen different names. Collecting them by hand is tedious, and the nodes that look plentiful are often dead by the time you paste them into a client. V2RayAggregator addresses that collection problem rather than the proxying problem. According to the README, its automation functions are all implemented on top of GitHub Actions, and the job is to test the speed of each free node pool and the nodes shared by bloggers, screen out relatively stable and high-speed nodes, and import them into the repository for sharing. The audience is therefore people who consume subscription links rather than people who operate proxy servers. The repository also ships a separate track for free airport nodes, which the README describes as a distinct group because some free airports only provide 1GB of traffic or are time-limited. That distinction matters: mixing short-lived trial nodes with long-lived public nodes would poison a single subscription list.

The Collect, Deduplicate, Speed-Test, Publish Pipeline

The mechanism visible in the repository is a scheduled pipeline. Two GitHub Actions workflows drive it, one named Collector and one named Airport_Collector, and both are referenced by status badges at the top of the README. Collection pulls from public sources and from airport subscriptions, then the README states that all duplicate nodes are removed. Speed measurement runs inside the GitHub Actions environment using LiteSpeedTest, and the README is explicit about the consequence: because the measurement happens there, there are many nodes in the United States, which cannot well represent node availability in a domestic network environment. After testing, nodes are sorted by average speed, and the README lists fixing sort based on average speed as a completed todo item. The output is written in several formats at once: Base64, mixed, and Clash YAML. The README notes that no additional conversion is performed, to avoid breaking nodes. The repository layout reflects this: Eternity, Eternity.txt and Eternity.yml sit at the top level for Group 1, EternityAir, EternityAir.txt and EternityAir.yml for Group 2, with the raw merged files under sub/ and supporting code under utils/ and update/.

Importing a Filtered Subscription Link

There is nothing to install if you only want the output. The README says to import the subscription link into the corresponding client, and to use a client that supports at least ss, ssr, vmess and trojan. Group 1 holds free public nodes filtered by the speed test, and the Clash variant is the file most clients want:

https://raw.githubusercontent.com/mahdibland/ShadowsocksAggregator/master/Eternity.yml

Paste that URL into your client's subscription field and update. The README states the filtered set contains 200 high-speed nodes, and that Group 1 is refreshed every 12 hours. Group 2 is the airport track and updates every 2 hours, so the README advises enabling auto-update in your client to get fresh nodes:

https://raw.githubusercontent.com/mahdibland/ShadowsocksAggregator/master/EternityAir.yml

If your client cannot read any of the published formats, the README points to online conversion services and gives a bianyuan API example. It also warns not to send your personal airport subscriptions through that public API and to run subconverter locally instead:

https://pub-api-1.bianyuan.xyz/sub?target=clash&url=https://raw.githubusercontent.com/mahdibland/ShadowsocksAggregator/master/Eternity.yml&insert=false

What you should see after importing is a node list whose entries carry country flags and IP addresses. The README explains that a repeated IP is usually the same host on different ports, not a bug.

The Speed Test Runs Where the Nodes Are Not

The most consequential limitation is stated plainly in the README rather than discovered by users. LiteSpeedTest executes inside GitHub Actions, so the measured latency and throughput describe a datacenter vantage point, not your connection. The README concedes that this produces many US nodes and cannot represent domestic network availability well. A node that ranks first in the published list may be unusable from your ISP, and the README acknowledges this directly: depending on your internet provider and location, some nodes might not work. There is a second limitation in the same family. The merged files under sub/, which contain every collected node rather than the filtered 200, are labelled for local testing only, and the README warns that the number of nodes is too high and your client will crash if you import them. Anyone who assumes the biggest file is the best file has misread the project. The project is also GPL-3.0, which is worth noting if you plan to redistribute the code rather than the subscription output.

V2RayAggregator Compared With Running Your Own Subconverter

The closest alternative in the README's own framing is a self-hosted subconverter setup. The difference is where the work happens. V2RayAggregator is a producer: it owns the collection, deduplication and speed-test stages, and you consume the result as a subscription URL. A local subconverter is a transformer: you supply the upstream subscription URLs and it rewrites them into your client's format, with no collection and no speed testing of its own. The README's warning about the public bianyuan API is the pivot between the two: it says not to use that API for personal airport subscriptions and to run subconverter locally instead. So if your problem is format conversion for subscriptions you already trust, V2RayAggregator is the wrong layer. If your problem is that you have no nodes at all and want a filtered list, the self-hosted route gives you nothing to convert. The two compose, but they do not substitute for each other.

Maintenance, Release History and Upgrade Cost

The repository is not archived, and the last push was on 2026-09-23. The only listed release is 1.0.0 from 2022-10-18, so versioned releases are not how this project communicates change. The README's recent todos are a better signal: items such as fixing region-based LiteSpeedTest, fixing sort based on average speed, adding separate files and functions for airports, and fixing the Clash template are all checked off, while cleanup of redundant files and functions on a dev branch remains open. That tells you the maintenance effort goes into the pipeline and its output files, not into tagged releases. For a consumer of the subscription links, upgrade cost is effectively zero: the raw.githubusercontent.com URLs are stable and the refresh happens on the project's schedule. For anyone forking the code, the cost sits in the GitHub Actions workflows and the Python under utils/ and update/, and the unchecked cleanup item suggests the codebase carries some redundancy. On licensing, GPL-3.0 governs the repository; the subscription files it publishes are data, and this article does not give legal advice on redistributing them.

Editorial conclusion

V2RayAggregator suits users who want a ready-made, speed-filtered subscription link without running their own collector, and who accept that the output is a moving target of free nodes. It is the wrong tool if you need guaranteed uptime, a privacy guarantee, or nodes that perform well on a mainland China connection, because the README states the speed tests run from GitHub Actions and therefore over-represent US nodes. Before importing anything, verify which of the four file groups matches your client, since Group 1 and Group 2 update on different schedules and the merged local-testing files are explicitly described as too large for a client to import safely.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. mahdibland/V2RayAggregator on GitHub
4. README
5. Releases