Overview

Relevant source files

• .github/build/friendly-filenames.json
• .github/workflows/release-win7.yml
• .github/workflows/release.yml
• .github/workflows/scheduled-assets-update.yml
• .github/workflows/test.yml
• README.md
• app/stats/channel_test.go
• core/core.go
• go.mod
• go.sum
• main/commands/base/execute.go
• proxy/wireguard/gvisortun/tun.go
• proxy/wireguard/server_test.go
• proxy/wireguard/tun.go
• transport/internet/reality/reality.go
• transport/internet/sockopt_other.go

Xray-core is a network proxy platform designed for anti-censorship and circumventing network restrictions. It provides a unified framework for accepting network connections using various protocols, processing data, and forwarding it through different outbound connections. The core functionality enables protocol transformation, traffic obfuscation, and intelligent routing to maintain connectivity in restrictive network environments.

This document provides a high-level overview of Xray-core's architecture, capabilities, and ecosystem. For detailed information about specific subsystems, see:

• Configuration system: Configuration System
• Proxy protocols: Proxy Protocols
• Transport and security: Transport and Security Layers
• Traffic routing: Traffic Management and Routing
• DNS resolution: DNS Resolution System
• Build and deployment: Build System and Deployment

System Identity and Versioning

Xray-core identifies itself through a semantic versioning scheme and build metadata. The version information is defined in core/core.go20-24:

Version_x byte = 26  // Major version
Version_y byte = 2   // Minor version  
Version_z byte = 6   // Patch version

The system automatically includes build information from Git VCS metadata when available core/core.go32-58 Version statements combine the semantic version with codename and platform details: "Xray 26.2.6 (Xray, Penetrates Everything.) <build> (<go-version> <os>/<arch>)" core/core.go60-72

Sources: core/core.go1-73

High-Level Architecture

Xray-core follows a layered architecture where configuration flows into the core, which orchestrates proxy protocols, transport mechanisms, and connection management. The following diagram shows the major subsystems and their relationships:

Sources: core/core.go1-73 README.md1-204

Core Capabilities

Protocol Support

Xray-core implements multiple proxy protocols for different use cases:

Protocol	Module Path	Primary Use Case
VLESS	proxy/vless	Lightweight protocol with XTLS Vision support
WireGuard	proxy/wireguard	VPN tunneling with gVisor userspace network stack
SOCKS	proxy/socks	Standard SOCKS4/5 proxy server
HTTP	proxy/http	HTTP/HTTPS CONNECT proxy
Dokodemo Door	proxy/dokodemo	Transparent proxy for capturing traffic
Freedom	proxy/freedom	Direct outbound connections with fragmentation
Blackhole	proxy/blackhole	Traffic blocking
Loopback	proxy/loopback	Internal routing

Sources: README.md136-159

Transport and Obfuscation

The transport layer provides multiple mechanisms for disguising and securing traffic:

Transport	Module Path	Description
REALITY	transport/internet/reality	TLS traffic mimicry with authentication
TLS/XTLS	transport/internet/tls	Standard TLS with fingerprinting support
SplitHTTP	transport/internet/splithttp	HTTP/1.1, HTTP/2, HTTP/3 obfuscation
WebSocket	transport/internet/websocket	WebSocket over HTTP/HTTPS
TCP	transport/internet/tcp	Raw TCP with header obfuscation
KCP	transport/internet/kcp	UDP-based custom protocol
HTTP/2	transport/internet/http	HTTP/2 and H2C transport
QUIC	transport/internet/quic	QUIC-based transport

Sources: transport/internet/reality/reality.go1-300 README.md1-204

REALITY Protocol Integration

REALITY is a critical anti-censorship component that mimics real TLS connections. The implementation in transport/internet/reality/reality.go1-300 provides:

• Client-side UConn structure transport/internet/reality/reality.go57-63 for establishing obfuscated connections
• Server-side Conn wrapper transport/internet/reality/reality.go37-55 for handling incoming REALITY connections
• Authentication using ECDH key exchange and HMAC verification transport/internet/reality/reality.go152-176
• Spider mechanism for crawling real websites when non-REALITY traffic is detected transport/internet/reality/reality.go186-272
• Support for post-quantum ML-DSA-65 signatures for additional verification transport/internet/reality/reality.go88-96

Sources: transport/internet/reality/reality.go1-300

WireGuard with gVisor

WireGuard integration uses a userspace network stack to provide VPN functionality without kernel modules. The implementation consists of:

• createGVisorTun() function proxy/wireguard/tun.go139-206 creates a TUN device using gVisor's network stack
• gvisorNet structure proxy/wireguard/tun.go120-137 implements the Tunnel interface for TCP/UDP dialing
• Promiscuous mode support proxy/wireguard/gvisortun/tun.go42-100 for capturing all packets and forwarding to handlers
• TCP and UDP forwarders proxy/wireguard/tun.go150-201 for handling connections in promiscuous mode

Sources: proxy/wireguard/tun.go1-207 proxy/wireguard/gvisortun/tun.go1-230

Dependency Management

Xray-core relies on a curated set of external libraries for cryptographic operations, network protocols, and platform integration. Key dependencies are specified in go.mod1-55:

Core Dependencies

Library	Purpose	Version Constraint
github.com/xtls/reality	REALITY protocol implementation	v0.0.0-20251014195629-e4eec4520535
github.com/refraction-networking/utls	TLS fingerprinting	v1.8.2
github.com/cloudflare/circl	Post-quantum cryptography	v1.6.3
gvisor.dev/gvisor	Userspace network stack	v0.0.0-20260122175437-89a5d21be8f0
golang.zx2c4.com/wireguard	WireGuard implementation	v0.0.0-20231211153847-12269c276173
golang.zx2c4.com/wintun	Windows TUN driver	v0.0.0-20230126152724-0fa3db229ce2
github.com/apernet/quic-go	QUIC protocol	v0.57.2-0.20260111184307-eec823306178
google.golang.org/protobuf	Protocol buffers	v1.36.11
google.golang.org/grpc	gRPC framework	v1.79.0

DNS and Network Utilities

Library	Purpose
github.com/miekg/dns	DNS protocol implementation
github.com/vishvananda/netlink	Linux netlink interface
go4.org/netipx	IP address utilities

Sources: go.mod1-55 go.sum1-156

Build and Distribution System

Build Workflow Details

The primary build workflow .github/workflows/release.yml1-288 implements a comprehensive multi-platform build system:

1. Asset Verification: .github/workflows/release.yml12-70 checks for required GeoIP/GeoSite data and Wintun drivers, triggering updates if missing
2. Build Matrix: .github/workflows/release.yml80-161 defines 30+ platform/architecture combinations using .github/build/friendly-filenames.json1-34 for naming
3. Compilation: .github/workflows/release.yml202-220 builds with Go's cross-compilation, using platform-specific flags and optimizations
4. Special Builds: .github/workflows/release-win7.yml1-181 provides Windows 7 support using a patched Go compiler from github.com/XTLS/go-win7

Asset Management

The automated asset update workflow .github/workflows/scheduled-assets-update.yml1-130 runs daily at 22:30 UTC and:

• Downloads GeoIP and GeoSite data from Loyalsoldier/v2ray-rules-dat repository .github/workflows/scheduled-assets-update.yml43-59
• Fetches Wintun drivers for Windows platforms (amd64, x86, arm64) .github/workflows/scheduled-assets-update.yml92-122
• Caches assets using GitHub Actions cache with keys xray-geodat-* and xray-wintun-* .github/workflows/scheduled-assets-update.yml61-66
• Verifies integrity using SHA256 checksums before caching .github/workflows/scheduled-assets-update.yml48-56

Sources: .github/workflows/release.yml1-288 .github/workflows/release-win7.yml1-181 .github/workflows/scheduled-assets-update.yml1-130 .github/build/friendly-filenames.json1-34

Platform Support

Xray-core provides extensive cross-platform support through conditional compilation and platform-specific implementations:

Supported Platforms

Operating System	Architectures
Linux	amd64, 386, arm64, arm (v5/v6/v7), riscv64, loong64, mips, mipsle, mips64, mips64le, ppc64, ppc64le, s390x
Windows	amd64, 386, arm64
macOS	amd64, arm64
FreeBSD	amd64, 386, arm64, arm (v7)
OpenBSD	amd64, 386, arm64, arm (v7)
Android	amd64, arm64

Platform-Specific Features

Socket options are implemented with platform-specific code:

• transport/internet/sockopt_other.go1-25 provides stub implementations for js, netbsd, openbsd, and solaris
• Platform-specific implementations exist for major operating systems to enable features like:
  • Transparent proxy (TProxy) on Linux
  • TCP Fast Open (TFO)
  • TCP congestion control
  • Socket buffer tuning
  • Interface binding

Sources: .github/workflows/release.yml80-161 .github/build/friendly-filenames.json1-34 transport/internet/sockopt_other.go1-25

Ecosystem and Integration

Installation Methods

Xray-core supports multiple installation approaches as documented in README.md50-76:

Method	Description	Source
Linux Script	Official installation script	XTLS/Xray-install
Docker	Official container images	ghcr.io/xtls/xray-core
Web Panel	Management interfaces	Remnawave, 3X-UI, Marzban, Hiddify
One-Click Scripts	Automated deployment	Various community scripts
Homebrew	macOS package manager	brew install xray

GUI Clients

The ecosystem includes numerous client applications README.md95-134:

Cross-Platform:

• v2rayN (Windows/Linux/macOS)
• Furious (Windows/Linux/macOS)
• AnyPortal (Windows/Android/Linux/macOS)

Mobile:

• v2rayNG (Android)
• Happ (iOS/tvOS/macOS)
• Streisand (iOS)

Router/Embedded:

• PassWall (OpenWrt)
• ShadowSocksR Plus+ (OpenWrt)
• fancyss (Asuswrt-Merlin)

API and Integration Tools

Third-party tools extend Xray-core's capabilities README.md143-153:

• xray-knife: Swiss Army knife for Xray operations
• libXray: Official library wrapper for embedding Xray
• xtls-sdk: SDK for application integration
• xray-api: API client libraries
• XrayR: Backend integration for panel systems

Sources: README.md1-204

Testing Infrastructure

The test workflow .github/workflows/test.yml1-78 runs on every push and pull request:

1. Asset Verification: Ensures GeoIP/GeoSite data is available before testing .github/workflows/test.yml9-35
2. Protocol Buffer Validation: Verifies all .pb.go files have consistent headers .github/workflows/test.yml37-51
3. Multi-Platform Testing: Runs tests on Windows, Ubuntu, and macOS with 1-hour timeout .github/workflows/test.yml53-77
4. Coverage: Executes all test suites using go test -timeout 1h -v ./...

Example test implementation verifying error handling in WireGuard server initialization proxy/wireguard/server_test.go1-52 demonstrates proper panic recovery and error propagation.

Sources: .github/workflows/test.yml1-78 proxy/wireguard/server_test.go1-52

Project Governance

Xray-core is an open-source project under the Mozilla Public License Version 2.0. The project originated as a fork of v2fly-core v1.0.0 (commit 9a03cc5) and has evolved independently with significant enhancements README.md168-170

The project maintains active community channels:

• Telegram: @projectXray, @projectXtls
• Official documentation: https://xtls.github.io
• Repository: https://github.com/XTLS/Xray-core

Sources: README.md32-48 README.md162-170