Onboarding: 2dust/v2rayN

Generated by RepoPilot · 2026-05-05 · Source

Verdict

WAIT — Mixed signals — read the receipts

• Last commit 1d ago
• 5 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors
• ⚠ Concentrated ownership — top contributor handles 53% of commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

v2rayN is a cross-platform GUI client (Windows, Linux, macOS) built in C# that manages and routes network traffic through proxy cores including Xray, sing-box, and v2fly. It solves the problem of configuring and switching between complex proxy protocols (VLESS, VMess, Trojan, Shadowsocks, etc.) without manually editing JSON config files, providing subscription management, latency testing, and routing rule editing through a unified interface. Monorepo under v2rayN/ containing ServiceLib (shared business logic and proxy config generation), AmazTool (auto-updater utility at v2rayN/AmazTool/), ServiceLib.Tests (xUnit tests for CoreConfig and Fmt), and ServiceLib.UdpTest (UDP/SOCKS5 testing utilities). Config generation for each core type lives in ServiceLib.Tests/CoreConfig/Singbox/ and ServiceLib.Tests/CoreConfig/V2ray/.

Who it's for

Users in regions with internet censorship who need a reliable, GUI-driven way to manage proxy servers and routing rules, as well as C#/.NET developers who want to contribute to a mature open-source proxy client that supports multiple upstream proxy cores via config generation.

Maturity & risk

The repo has strong CI coverage with multiple GitHub Actions workflows (build-all.yml, build-linux.yml, build-osx.yml, build-windows.yml) targeting all three platforms, and includes unit tests under ServiceLib.Tests/ covering core config generation for both Xray and sing-box. Active commit activity badges and a Telegram channel suggest regular maintenance. Verdict: production-ready and actively developed.

The project has a single primary maintainer (2dust) which poses a bus-factor risk for long-term sustainability. It depends on external proxy cores (Xray, sing-box) as submodules (.gitmodules), meaning breaking changes upstream can affect functionality. The mix of 1.37M lines of C# with shell packaging scripts (package-debian.sh, package-rhel.sh, package-osx.sh) adds platform-specific complexity that may lag behind OS updates.

Active areas of work

Based on visible structure, active work includes multi-platform packaging (separate CI workflows for debian, rhel, rhel-riscv, osx, windows), RISC-V Linux support (package-rhel-riscv.sh), UDP proxy testing (ServiceLib.UdpTest with STUN/NTP/DNS/Minecraft-BE testers), and expanded sing-box core config support alongside Xray.

Get running

git clone --recurse-submodules https://github.com/2dust/v2rayN.git cd v2rayN/v2rayN

Requires .NET 8 SDK

dotnet restore dotnet build

To run tests

dotnet test ServiceLib.Tests/ServiceLib.Tests.csproj

Daily commands: cd v2rayN/v2rayN dotnet run --project <MainProjectName>.csproj

For Linux packaging: bash package-debian.sh or bash package-rhel.sh

For macOS packaging: bash package-osx.sh

Map of the codebase

• v2rayN/ServiceLib/Handler/ConfigHandler.cs — Central configuration manager that reads/writes all proxy server profiles, subscription data, and app settings — the single source of truth for app state.
• v2rayN/ServiceLib/Handler/CoreConfigHandler.cs — Orchestrates generation of the final config file passed to xray/sing-box/other cores; every supported protocol must flow through this handler.
• v2rayN/ServiceLib/Handler/Builder/CoreConfigContextBuilder.cs — Builds the per-request configuration context (inbounds, outbounds, routing rules) that is serialized and handed to the running proxy core process.
• v2rayN/ServiceLib/Handler/Fmt/FmtHandler.cs — Dispatch hub for all URI/share-link parsing and serialization across every supported protocol (vmess, vless, trojan, ss, hysteria2, etc.).
• v2rayN/ServiceLib/Global.cs — Defines global constants, version strings, and shared singleton references used across the entire service layer.
• v2rayN/ServiceLib/Events/EventChannel.cs — Reactive event bus (ReactiveUI / Rx) that decouples UI view-models from background services — understanding this is mandatory before adding any feature.
• v2rayN/ServiceLib/Handler/ConnectionHandler.cs — Manages the lifecycle of the proxy core process (start, stop, restart, log streaming) and bridges OS-level process management to the UI layer.

How to make changes

Add a new proxy protocol (e.g. a new URI scheme)

1. Add a new enum value to identify the protocol type (v2rayN/ServiceLib/Enums/EConfigType.cs)
2. Create a new formatter class inheriting BaseFmt with Decode/Encode methods for the URI scheme (v2rayN/ServiceLib/Handler/Fmt/BaseFmt.cs)
3. Register the new formatter in the protocol dispatch switch (v2rayN/ServiceLib/Handler/Fmt/FmtHandler.cs)
4. Add outbound generation logic for the new protocol inside the context builder (v2rayN/ServiceLib/Handler/Builder/CoreConfigContextBuilder.cs)
5. Add round-trip unit tests for the new URI formatter (v2rayN/ServiceLib.Tests/Fmt/FmtHandlerTests.cs)

Support a new proxy core binary

1. Add a new enum value for the core binary (v2rayN/ServiceLib/Enums/ECoreType.cs)
2. Add core-specific config generation (inbounds, outbounds, DNS format) by extending or branching the handler (v2rayN/ServiceLib/Handler/CoreConfigHandler.cs)
3. Update process launch arguments and binary resolution for the new core (v2rayN/ServiceLib/Handler/ConnectionHandler.cs)
4. Add or update constants (default ports, config filenames) for the new core (v2rayN/ServiceLib/Global.cs)

Add a new application-level event (cross-component notification)

1. Define a new typed event payload class (v2rayN/ServiceLib/Events/AppEvents.cs)
2. Publish the event from the appropriate service using the event channel (v2rayN/ServiceLib/Events/EventChannel.cs)
3. Subscribe and react to the event in the relevant view-model, inheriting from MyReactiveObject (v2rayN/ServiceLib/Base/MyReactiveObject.cs)

Add a new routing rule mode

1. Add the new mode value to the routing mode enum (v2rayN/ServiceLib/Enums/ERuleMode.cs)
2. Persist the new setting alongside existing routing config in the config handler (v2rayN/ServiceLib/Handler/ConfigHandler.cs)
3. Implement the routing rule generation logic for the new mode in the context builder (v2rayN/ServiceLib/Handler/Builder/CoreConfigContextBuilder.cs)

Why these technologies

• C# / .NET (cross-platform) — Allows a single codebase to target Windows (WPF/Avalonia), Linux, and macOS while sharing all business logic in ServiceLib.
• ReactiveUI / System.Reactive — Provides a clean MVVM binding and event-bus pattern that decouples background

Traps & gotchas

1. The repo uses git submodules (.gitmodules) for proxy core binaries — cloning without --recurse-submodules will result in missing core executables and runtime failures. 2) Actual proxy cores (xray, sing-box binaries) must be downloaded separately or via the app's built-in updater; the C# code only generates configs and manages processes. 3) On Linux/macOS, the app requires execute permissions on core binaries (chmod +x). 4) The RISC-V build (package-rhel-riscv.sh) likely requires a cross-compilation toolchain not present by default. 5) Directory.Packages.props enforces centralized package versioning — adding NuGet packages directly in .csproj without going through this file will cause build errors.

Architecture

Concepts to learn

• SOCKS5 UDP ASSOCIATE — ServiceLib.UdpTest/Socks5UdpChannel.cs implements SOCKS5 UDP tunneling, which is distinct from TCP SOCKS5 and requires understanding the UDP ASSOCIATE command for proxying UDP traffic.
• STUN Protocol (NAT traversal) — StunService.cs uses STUN to detect NAT type and public IP — necessary for testing whether UDP actually traverses the proxy correctly.
• Proxy subscription links (vmess/vless/trojan URI schemes) — The Fmt layer (FmtHandlerTests.cs) parses these custom URI schemes used to share proxy server configs — understanding the encoding (base64, JSON) is critical for the import feature.
• TUN mode (Layer 3 proxy) — sing-box and Xray support TUN interfaces to intercept all system traffic at the network layer without per-app proxy settings — v2rayN generates configs that enable this mode.
• Centralized NuGet package versioning (Directory.Packages.props) — v2rayN uses MSBuild's Central Package Management via Directory.Packages.props, which means package versions are declared once solution-wide — adding packages incorrectly breaks the entire build.
• Child process proxy core management — v2rayN doesn't implement proxying itself — it generates JSON config files and manages Xray/sing-box as child processes, making process lifecycle management and config serialization the core architectural concern.
• GFW routing rules (geoip/geosite) — v2rayN routing configuration relies on geoip and geosite data files used by Xray/sing-box to route traffic by region or domain category — these are binary format files, not plain JSON.

Related repos

• hiddify/hiddify-app — Direct alternative cross-platform GUI proxy client supporting sing-box, targeting the same censorship-circumvention use case.
• Qv2ray/Qv2ray — Predecessor/alternative Qt-based GUI for v2ray/Xray that inspired many design decisions in v2rayN.
• XTLS/Xray-core — Primary upstream proxy core that v2rayN wraps — understanding its config format is essential for ServiceLib config generation code.
• SagerNet/sing-box — Second major upstream proxy core supported by v2rayN, with dedicated config generation at CoreConfigSingboxServiceTests.cs.
• 2dust/v2rayNG — Sister project by the same maintainer — Android GUI client for the same proxy ecosystem, sharing conceptual design.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for FmtHandler covering all supported proxy protocol parsers

The file v2rayN/ServiceLib.Tests/Fmt/FmtHandlerTests.cs already exists but likely has incomplete coverage for all protocol formats (vmess, vless, trojan, shadowsocks, hysteria2, etc.) that v2rayN supports. Since this is a GUI client that parses share links from clipboard/QR codes, a bug in any protocol parser silently breaks server imports. Adding thorough round-trip parse/generate tests for every EConfigType enum value would catch regressions in link parsing.

• [ ] Open v2rayN/ServiceLib/Enums/EConfigType.cs and enumerate all supported config types (VMess, VLESS, Trojan, Shadowsocks, Hysteria2, TUIC, WireGuard, etc.)
• [ ] Open v2rayN/ServiceLib.Tests/Fmt/FmtHandlerTests.cs and identify which EConfigType values currently lack test cases
• [ ] For each missing protocol, add a parameterized test that (a) creates a ProfileItem fixture, (b) calls the relevant Fmt.ShareLink/Encode method, (c) asserts the output URI matches a known-good string, and (d) round-trips it back through Fmt.Resolve/Decode and compares all fields
• [ ] Add edge-case tests: malformed URIs, missing required fields, unicode characters in remarks/passwords
• [ ] Run the ServiceLib.Tests project and confirm all new tests pass in CI via the existing build-windows.yml workflow

Add unit tests for CoreConfigSingboxService and CoreConfigV2rayService covering edge-case proxy configurations

v2rayN/ServiceLib.Tests/CoreConfig/Singbox/CoreConfigSingboxServiceTests.cs and CoreConfigV2rayServiceTests.cs exist but, given the complexity of generating valid sing-box/xray JSON configs (outbounds, routing rules, mux, reality, transport), they almost certainly lack coverage for edge cases like proxies with multiple transports (ws+tls, grpc+reality), chain proxies, or custom DNS settings. A bug here generates a broken core config that fails silently at runtime.

• [ ] Review v2rayN/ServiceLib.Tests/CoreConfig/CoreConfigTestFactory.cs to understand the existing fixture builder and identify which ProfileItem combinations are not yet exercised
• [ ] Add test cases in CoreConfigSingboxServiceTests.cs for: VLESS+Reality+gRPC, VMess+WebSocket+TLS, Hysteria2, TUIC, and a chained proxy scenario
• [ ] Add equivalent test cases in CoreConfigV2rayServiceTests.cs for xray-core configs: XTLS-Vision, VLESS+WS, VMess+HTTP/2
• [ ] In each test, deserialize the generated JSON string and assert critical keys (outbound type, tls.enabled, transport.type, server, server_port) match the input ProfileItem values
• [ ] Verify the Context builder tests in CoreConfigContextBuilderTests.cs also cover routing rule generation when both direct and proxy rules are present

Extract and unit-test Utils.cs and FileUtils.cs helper methods in ServiceLib

v2rayN/ServiceLib/Common/Utils.cs and FileUtils.cs are shared utility files used across the entire application (URI building, version comparison, path resolution, etc.). There are currently no dedicated test files for these classes in ServiceLib.Tests. Because these helpers underpin subscription updates, core process management, and config file I/O, an untested regression (e.g. in version comparison used to decide whether to auto-update) can affect all users silently.

• [ ] Create v2rayN/ServiceLib.Tests/Common/UtilsTests.cs and add tests for every public static method in ServiceLib/Common/Utils.cs (e.g. GetVersion, IsNullOrEmpty wrappers, url-encode helpers, version string comparison logic)
• [ ] Create

Good first issues

1. Add missing unit tests for FmtHandler edge cases (malformed vmess:// or vless:// URIs) — FmtHandlerTests.cs likely has gaps for error paths. 2) The ServiceLib.UdpTest project has multiple tester implementations (DnsService, NtpService, McBeService, StunService) but no visible test coverage — add xUnit tests for each IUdpTest implementation. 3) Improve the AmazTool/Utils.cs with tests — the updater utility has no corresponding test project, making it a high-risk untested component.

Top contributors

• @DHR60 — 49 commits
• @2dust — 33 commits
• @bonjour-py — 4 commits
• @xujiegb — 4 commits
• @aleksandr-miheichev — 3 commits

Recent commits

• 8450f2e — Add bind interface (#9222) (DHR60)
• 37ef25c — Fix (#9235) (DHR60)
• 0fac18b — Fix (#9230) (DHR60)
• 3ccd59d — Fix (#9224) (DHR60)
• 6c38a08 — up 7.21.1 (2dust)
• f8f7fee — Disable auto-adjust main list column width desktop (2dust)
• 3e157b0 — Update 'CheckServerSettings' message (2dust)
• 49d197e — i18n(ru): translate new strings and fix terminology casing (#9207) (aleksandr-miheichev)
• b6f2912 — Remove EchForceQuery (#9214) (DHR60)
• 05e349e — Code clean (2dust)

Security observations

• High · Potential Command Injection via Process Utilities — v2rayN/ServiceLib/Common/ProcUtils.cs. The file ProcUtils.cs likely handles process spawning for external core binaries (Xray, sing-box, etc.). If user-controlled input (e.g., server addresses, proxy settings, subscription URLs) is passed unsanitized to process arguments, it could lead to command injection. GUI VPN clients frequently construct command-line arguments from configuration data. Fix: Ensure all external process arguments are constructed using parameterized argument arrays rather than string concatenation. Validate and sanitize all user-supplied configuration values before passing them to Process.Start() or equivalent. Use ProcessStartInfo with explicit argument lists.
• High · Insecure Deserialization of Subscription/Configuration Data — v2rayN/ServiceLib/Common/JsonUtils.cs, v2rayN/ServiceLib/Common/YamlUtils.cs. JsonUtils.cs and YamlUtils.cs handle deserialization of external data including subscription content fetched from remote URLs and imported configuration files. Malicious subscription providers or MITM attackers could craft payloads to exploit deserialization vulnerabilities, potentially leading to arbitrary code execution or unexpected application behavior. Fix: Use strict type-safe deserialization with explicit type mappings. Avoid using dynamic or object types during deserialization. Validate all deserialized data against an expected schema. Consider using System.Text.Json with TypeInfoResolver for safer deserialization. For YAML, avoid deserializing to arbitrary object types.
• High · Unvalidated URL Fetching for Subscription Updates — v2rayN/ServiceLib/Handler/ (subscription-related handlers). The application fetches subscription data from user-configured URLs. Without proper URL validation and certificate pinning or strict TLS verification, this could expose the application to SSRF (Server-Side Request Forgery) attacks, allowing access to internal network resources, or to MITM attacks that inject malicious proxy configurations. Fix: Validate subscription URLs against an allowlist of safe schemes (https:// only). Enforce strict TLS certificate validation. Implement certificate pinning for known update endpoints. Add SSRF protection by blocking requests to private IP ranges. Set reasonable timeouts and response size limits.
• High · Unsafe Auto-Update Mechanism — v2rayN/AmazTool/UpgradeApp.cs. The AmazTool/UpgradeApp.cs handles application auto-updating. If update packages are downloaded over HTTP or without cryptographic signature verification, an attacker performing a MITM attack could substitute a malicious binary, leading to arbitrary code execution with the user's privileges. Fix: Ensure all update downloads use HTTPS exclusively. Implement cryptographic signature verification (e.g., using RSA or Ed25519) for all downloaded update packages before execution. Compare file hashes against values fetched from a separate, authenticated endpoint. Never execute downloaded files without signature validation.
• Medium · Sensitive Configuration Data Stored Without Encryption — v2rayN/ServiceLib/Handler/ (config management), application data directory. Application configuration including proxy server addresses, ports, authentication credentials (usernames/passwords for proxy servers), and potentially private keys may be stored in plaintext configuration files (e.g., guiNConfig.json or similar). This poses a risk if the system is compromised or if the configuration files are inadvertently shared. Fix: Encrypt sensitive fields (passwords, private keys, UUIDs used as credentials) at rest using platform-specific secure storage APIs (e.g., Windows DPAPI via ProtectedData class, macOS Keychain, Linux Secret Service). At minimum, restrict file permissions to the current user only.
• Medium · Arbitrary File Write via Path Traversal in File Utilities — v2rayN/ServiceLib/Common/FileUtils.cs. FileUtils.cs handles file operations for configuration import/export and potentially for writing core configuration files. If file paths derived from user input or external data (e.g., subscription content containing file paths) are not properly sanitized, path traversal attacks (../../../) could allow writing files to arbitrary locations on the filesystem. Fix: Canonicalize all file paths using Path.GetFullPath() and validate they reside within expected application directories. Reject any paths containing '..' sequences or absolute paths from external sources. Use a whitelist approach for allowed file locations.
• Medium · QR Code Data Injection Risk — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.