v2ray-configs: a shared pool of free V2ray configurations

A configuration pool, not a client

The repository description says it in one line: free V2ray configs, updating every 15 minutes. The README calls it a community maintained repository offering free V2ray configs to help you browse securely and privately, and the primary language of the repository is listed as HTML, which tells you that the centre of gravity is a static site rather than a library.

So this is not a VPN implementation. There is no client, no protocol code and no server here. What the repository holds is a set of connection strings, in the formats V2ray clients understand, gathered from public places and republished in a shape that a client can consume automatically.

That shape is what makes the project usable. The key features list names multi-protocol compatibility across VMess, VLESS, Trojan, Shadowsocks, SSR, TUIC, Hysteria2 and Warp, auto-updating configurations every fifteen minutes, organisation by protocol type, base64 encoding for convenience and frequently refreshed sources.

The audience is therefore two groups. One is users behind restrictive networks who want a working configuration to test, and the other, more interesting for an engineer, is people who want to know which protocols and transports are worth setting up properly, since the repository is effectively a live, continuously refreshed sample of what people are actually running.

The homepage is a separate deployment, linked from the README, and the repository itself also carries the static content that gets deployed to GitHub Pages through its own workflow.

Two workflows, one update cycle

The badges at the top of the README show the automation. One workflow is named for updating the V2ray configs and one for deploying static content to Pages, and both are shown with their status on the main branch.

The fifteen minute cadence comes from the first of those. The repository is not a place where a human curates configurations; it is a pipeline that fetches, filters, splits and re-publishes them, and the output is a set of plain text files served as raw URLs.

The tooling is small, and the requirements file shows it. It pins two packages:

pybase64==1.4.1
requests==2.33.0

pybase64 handles the encoding that the feature list mentions as a convenience, and requests does the fetching. There is no heavy framework, no database and no scheduler library in the runtime dependencies, which fits a pipeline that runs on a timer in CI.

The directory layout matches that story. There is a src directory holding the pipeline code, a subscriptions directory holding the published output, a public directory for the static site assets, a docs directory, an appsettings.json at the root for the pipeline configuration, a requirements.txt, a CODE_OF_CONDUCT.md and a CONTRIBUTING.md.

The last push to the repository was on 2026-10-20, and the repository is not archived, so the pipeline is running. There are no GitHub releases, which makes sense: the artefact here is not a versioned package but a moving set of files, and pinning a release would defeat the purpose.

Four ways to fetch: everything, the best, split files, or one protocol

The getting started section offers two choices, and then a set of subscription URLs. You can use the subscription URLs provided, or manually download configs from the subscriptions folder.

The main file is described as all protocols, with more than 7500 configs:

https://raw.githubusercontent.com/MatinGhanbari/v2ray-configs/main/subscriptions/v2ray/all_sub.txt

Then there is what the README calls the super subscription, described as the best configs over all configs by testing results:

https://raw.githubusercontent.com/MatinGhanbari/v2ray-configs/main/subscriptions/v2ray/super-sub.txt

That one is the interesting file, and it is worth being precise about what the README claims and what it does not. It says the selection is made by testing results, which means there is a measurement step somewhere in the pipeline that ranks configurations. It does not describe how the test is done, what a passing test means, or how often the ranking is recomputed, so treat it as a curated subset rather than a guarantee of quality.

The split subscriptions exist for clients that cannot handle a very large file. They hold 200 configs each, and the README notes that the sub id can be changed from 1 to 39:

https://raw.githubusercontent.com/MatinGhanbari/v2ray-configs/main/subscriptions/v2ray/subs/sub1.txt
https://raw.githubusercontent.com/MatinGhanbari/v2ray-configs/main/subscriptions/v2ray/subs/sub2.txt
https://raw.githubusercontent.com/MatinGhanbari/v2ray-configs/main/subscriptions/v2ray/subs/sub3.txt
https://raw.githubusercontent.com/MatinGhanbari/v2ray-configs/main/subscriptions/v2ray/subs/sub39.txt

Finally there are per protocol files under a filtered directory, with Hysteria2 marked as recommended:

https://raw.githubusercontent.com/MatinGhanbari/v2ray-configs/main/subscriptions/filtered/subs/hysteria2.txt
https://raw.githubusercontent.com/MatinGhanbari/v2ray-configs/main/subscriptions/filtered/subs/vmess.txt
https://raw.githubusercontent.com/MatinGhanbari/v2ray-configs/main/subscriptions/filtered/subs/vless.txt
https://raw.githubusercontent.com/MatinGhanbari/v2ray-configs/main/subscriptions/filtered/subs/trojan.txt
https://raw.githubusercontent.com/MatinGhanbari/v2ray-configs/main/subscriptions/filtered/subs/ss.txt

The protocol split is the practical part of the design. A client can be pointed at one file for one protocol, which keeps the payload small and makes it obvious which transport is actually reachable from your network.

Which clients consume these strings

The README names the clients under a V2ray clients heading: the Hiddify App and Nekoray, each linked to its repository. Those two are what the format targets, and the topic list on the repository gives a wider view of the ecosystem, with v2rayng, v2ray-core, shadowsocks, trojan, vless, vmess, v2config, vpn and vpn-service among the tags, and gfw as the censorship related one.

The distinction between a config file and a subscription matters technically. A config string describes one connection, and a subscription is a list of them that the client fetches and refreshes on its own. That is why the files are base64 encoded, since a subscription payload is normally a base64 blob that the client decodes and re-encodes into its own list.

So the practical workflow is a URL pasted into a client, and the client handles the rest. This is also where the design decision has consequences. A subscription that refreshes every fifteen minutes means the set of servers your traffic goes through can change without you doing anything, which is convenient for staying online and is exactly what makes the source of those servers worth thinking about.

Contribution is handled through pull requests, with the README saying that a configuration file can be contributed by opening a pull request and that contributions will be reviewed. For a repository whose contents are gathered from public sources, that review step is the main quality control in the pipeline, and its strength is not something the README quantifies.

The licence covers the code, not the connections

The license clarification section is the most important paragraph in the README for anyone considering using these configurations for anything that matters.

It separates two things. The source code, scripts and documentation in the repository are licensed under the MIT licence, with the full text in the LICENSE file, and you may use, modify and redistribute that code, including for commercial purposes, provided you retain the original copyright notice and permission notice.

The configuration files are different. The README states that the V2ray configuration files, VMess, VLESS, Trojan, Shadowsocks and the rest, published in the repository are aggregated from public internet sources and public GitHub repositories, and the section continues past what is quoted here.

That distinction is the whole risk profile of the project in one paragraph. MIT on the pipeline says nothing about the servers the strings point at, and an aggregated configuration is a pointer to somebody else's machine. If you import one of these into a client, your traffic is routed through a host you did not choose, did not audit and cannot control, and in exchange you get a working connection rather than a guarantee of one.

There is also a governance angle. The repository is community maintained, the README invites configuration files through pull requests, and the topic list includes vpn-service and gfw, which tells you the intent is censorship circumvention. For a project whose whole value is a large, constantly changing list of third-party endpoints, the review process and the update cadence are the product, and neither is documented in detail.

A static site front end and a multi-language README

The repository is presented as a web project as much as a data project. The homepage is a separate deployment linked from the README, the public directory holds the static assets for it, and one of the two GitHub workflows is specifically for deploying static content to Pages.

The README itself is generated in many languages. The language block links to translated views of the repository description through an external viewer, covering English, Simplified Chinese, Traditional Chinese, Japanese, Korean, Hindi, Thai, French, German, Spanish, Italian, Russian, Portuguese, Dutch, Polish, Arabic, Persian, Turkish, Vietnamese and Indonesian. That is a long list, and it tells you where the project's users are.

The badges are the other signal of how the project is run. There are status badges for the update workflow and the static deployment, a last commit badge, an MIT badge, a repository size badge and a stars badge, and the README embeds a stars chart, a repository activity chart and a star history chart. For a repository whose content is machine generated and refreshed on a timer, the activity chart is the most honest of these, since it shows commits arriving on their own schedule.

The homepage for the project is the hosted deployment, and the repository itself is where the data and the pipeline live. The two are coupled by the static workflow, which is what makes the URLs in the README usable as subscription links, since the raw file URLs point at the main branch of the repository rather than at a release.

Editorial conclusion

Adopt v2ray-configs as a testing source of connection strings, or as a quick way to see which protocols are worth configuring properly, rather than as infrastructure for anything you care about. Do not adopt it as a production dependency, because the configurations are aggregated from public internet sources and therefore from servers whose operator you do not know and cannot audit, and because a subscription URL that refreshes every fifteen minutes can hand your traffic to a different endpoint without warning. Verify first which protocol you need and read the license clarification section, which states that the MIT licence covers the code, scripts and documentation while the configuration files themselves come from elsewhere, then check the last commit date before you trust the content of a subscription file.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. MatinGhanbari/v2ray-configs on GitHub
4. Project website
5. README