v2go: A Go-Based V2Ray Config Aggregator That Live-Tests Every Subscription Entry

What v2go Solves and Who It Is For

v2go addresses a specific pain point for users of V2Ray-based proxy subscriptions: most public subscription lists are cluttered with dead or duplicate servers. The original Python aggregator, Epodonios/v2ray-configs, collected configs but did not verify they worked. v2go is a Go rewrite that adds a live-testing stage. It is aimed at individuals who run their own subscription service, or who want a curated list of working servers without manually checking each one. The README positions it as a high-performance replacement, claiming to process 20,000+ configs in 11 seconds, which is 99.7% faster than the Python version. That speed matters because the pipeline runs hourly via GitHub Actions, fetching around 50,000 raw configs each time. The target user is someone who wants a fresh, deduplicated, and verified subscription file on a regular basis, not a one-off script.

The Five-Stage Pipeline: From Fetch to Publish

The core of v2go is a five-stage pipeline, as described in the README. First, Fetch downloads roughly 35 public subscription sources concurrently, handling both base64 and plain-text formats. Second, Screen performs a fast TCP connectivity check and rejects invalid parameters that could crash clients. It also deduplicates based on identity: protocol, credentials, host, and port. This means two configs with different names but the same underlying server are treated as one. Third, Live test is the distinctive step. Each surviving config is converted into an outbound-only Xray configuration and run in an embedded Xray-core instance in memory. An HTTP request to a 204 test endpoint is made through the proxy. Only configs that successfully pass real traffic are kept. The README emphasizes that no external binaries, no subprocesses, and no open ports are used. Fourth, Publish renames working configs to a consistent format like 'v2go | DE | VLESS | 1', tags them by GeoIP country, and writes them into subscription files. Configs with Cloudflare IPs are collected into a dedicated file. Fifth, Clean up removes subscription files that have not been refreshed within 24 hours. This automation ensures the output stays current.

Live Testing vs. Port Scanning: The Key Difference

The README makes a pointed argument: a TCP port check only proves that something answers on the server's port, but it says nothing about whether the proxy behind it works. v2go's live-test stage addresses this by running each config through an actual Xray instance. The mechanism is straightforward: the converter turns a share link into Xray outbound JSON, the tester runs that in an embedded Xray-core, and then makes an HTTP request through it to a 204 endpoint. If the request succeeds, the config is kept. This is a meaningful improvement over simple port scanning, because many dead configs pass a port scan but fail to route traffic. The trade-off is that live testing takes time and resources. A typical run deduplicates 50,000 raw configs to 10,000-15,000 candidates, then live-tests all of them in about two minutes. That is fast, but it requires significant network bandwidth and CPU. The README notes that concurrency above 500 saturates the network and produces worse results, so there is a practical ceiling.

Getting It Running: Commands and Configuration

To build and run v2go, you need Go 1.26 or higher and Git. The quick start is simple: clone the repository with --depth=1, cd into it, run 'go build -o aggregator .', then set the file descriptor limit with 'ulimit -n 65535' and execute './aggregator'. The GeoIP database is downloaded automatically on first run. For scanning your own list, the command is './aggregator -input my-configs.txt'. The input file can be a plain list of share links, one per line, or a base64-encoded subscription. Everything else in the pipeline is unchanged, so the usual output files are produced. The live-test stage can be tuned with environment variables: V2GO_TEST_CONCURRENCY defaults to 500, and V2GO_TEST_TIMEOUT defaults to 5 seconds per config. The README warns that raising concurrency above 500 makes results worse, not faster. Tests can be run with 'go test ./...'. This is a straightforward setup, but the ulimit command is a Unix-specific requirement that may trip up Windows users.

Output Structure and Subscription Links

The output is organized into several directories and files. The main file is AllConfigsSub.txt, containing all working configs in plain text. Sub1.txt through SubN.txt split the list into 500-config chunks. There is a Base64/ directory with base64-encoded variants of the Sub files. Splitted-By-Protocol/ organizes configs by protocol, with files like vless.txt, vmess.txt, ss.txt, trojan.txt, hy2.txt, tuic.txt, and cloudflare.txt. Note the encoding quirk: vmess.txt is plain text, while every other file in that directory is base64-encoded. This is a potential source of confusion for users who expect consistency. Splitted-By-Country/ organizes by GeoIP location, such as US.txt or DE.txt. There is also working-live.txt, which streams working configs the moment they pass, before the run completes. This is useful if a run crashes part-way, because the file retains all configs verified up to that point, unmodified and with original names. The README provides raw GitHub subscription links for the main list, country-specific lists (replace XX with a country code), protocol-specific lists, and split lists. Stale files are removed automatically after 24 hours, so the links always point to fresh content.

Limitations and Failure Modes

The most obvious limitation is that the live-test stage does not cover all supported protocols. The README lists VLESS, VMess, Trojan, Shadowsocks, and Hysteria2 as covered in live testing, including TLS, REALITY, WebSocket, and gRPC transports. However, TUIC and ShadowsocksR (SSR) are not mentioned in the live-test coverage. This means configs using those protocols may pass the screen stage but are not verified with real traffic, or they may be excluded entirely. The README does not clarify which case applies. Another limitation is location dependency. The README explicitly states that test results depend on where you run from. A config that works from a datacenter in the United States may be unreachable from a restrictive ISP, and a config that CI discards may work perfectly from your network. This is a fundamental issue for any aggregator that tests from a single location. The v2go project tries to mitigate this by allowing users to scan their own lists with the -input flag, but the automated pipeline still uses the project's own location. Additionally, the concurrency limit of 500 means that on very fast networks, the testing may become a bottleneck, though the README claims that higher concurrency degrades results.

Alternatives and Their Different Approaches

The primary alternative is the original Python project, Epodonios/v2ray-configs, which v2go is a rewrite of. The difference in approach is fundamental: the Python version likely did not have a live-testing stage, or if it did, it was slower. The README claims v2go is 99.7% faster, processing 20,000+ configs in 11 seconds. That speed advantage comes from Go's concurrency model and the embedded Xray-core, which avoids subprocess overhead. Another alternative is to manually curate a subscription list using tools like v2rayN or v2rayNG, which have built-in testing but are client-side and not automated. Those tools test configs on the device, not in a batch pipeline. A third alternative is to use a commercial subscription service that provides pre-tested lists, but those are closed-source and may not be free. The key difference with v2go is its automation and the live-testing mechanism that verifies actual traffic, not just port availability. For users who need a self-hosted solution, v2go offers a distinct approach.

Maintenance and License Considerations

v2go is licensed under GPL-3.0, which means any derivative work must also be released under GPL-3.0. This is a copyleft license, so if you modify and distribute v2go, you must make your source code available under the same license. This is not legal advice, but it is a practical consideration for anyone who wants to embed v2go in a proprietary product. The project is actively maintained, with recent releases v1.3.1 and v1.3 dated 2026-08-06 and 2026-08-05, respectively. The last push is also from 2026-08-06, indicating ongoing development. The maintenance cost is moderate: the pipeline runs hourly via GitHub Actions, which requires a GitHub repository and Actions minutes. The GeoIP database is downloaded automatically, but it may need periodic updates. The README does not mention a specific upgrade path, but the Go toolchain makes rebuilding straightforward. The test suite is simple to run with 'go test ./...'. One maintenance concern is the dependency on Xray-core as an embedded library. If Xray-core changes its API, v2go may need updates to remain compatible. The release notes for v1.3 mention 'Live config testing with embedded Xray-core', so this is a recent addition, and future changes could affect stability.

Editorial conclusion

Adopt v2go if you need a self-hosted, continuously updated V2Ray subscription aggregator that filters out dead configs by real traffic testing, and you are comfortable with GPL-3.0 and the resource demands of concurrent testing. Do not use it if you require support for all listed protocols in the live-test stage (SSR and TUIC are not covered) or if your network blocks outbound connections to test endpoints. Before relying on it, verify that your Go version is 1.26 or higher, check the output file naming and encoding conventions (vmess.txt is plain text, others base64), and confirm that the hourly GitHub Actions schedule fits your update needs.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes