Overview

Relevant source files

• .github/workflows/docker.yml
• .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/client.go
• proxy/wireguard/server.go
• transport/internet/reality/reality.go

Purpose and Scope

This document provides a high-level introduction to Xray-core, a unified platform for anti-censorship network tools. It covers the project's purpose, core architectural design, key capabilities, and how the major components interact.

For detailed information about specific subsystems, see:

• Configuration system: Configuration System
• Transport and security protocols: Transport and Security Layer
• Proxy protocol implementations: Proxy Protocols
• Routing and traffic management: Routing and Dispatching
• DNS resolution: DNS System
• Build and deployment processes: Build and Deployment

Sources: README.md1-50 core/core.go1-44

What is Xray-core?

Xray-core is a unified network platform designed to provide anti-censorship tools and secure tunneling capabilities. The project originates from the XTLS protocol and has evolved into a comprehensive suite of network utilities that can accept incoming connections with various protocols, process traffic, and forward it through different connection types on demand.

The core mission statement, as defined in the codebase, is: "A unified platform for anti-censorship." The current codename is "Xray, Penetrates Everything."

Sources: core/core.go19-29 README.md1-50

Version and Build Information

Xray-core uses a semantic versioning scheme with three components: Version_x, Version_y, and Version_z. The version information is defined in core/core.go:

This translates to version 25.12.8. The version statement also includes build information and runtime details (Go version, OS, architecture) for debugging and compatibility verification.

Component	Value	Purpose
Version_x	25	Major version
Version_y	12	Minor version
Version_z	8	Patch version
build	"Custom" (default)	Build identifier
codename	"Xray, Penetrates Everything."	Project tagline
intro	"A unified platform for anti-censorship."	Mission statement

Sources: core/core.go19-43

Core Architecture Components

Xray-core is organized into several major subsystems that work together to provide a flexible, extensible proxy platform:

Diagram: Core Component Architecture with Code Entities

The architecture follows a layered design:

1. Core Platform Layer: The core.Instance serves as the main orchestrator, managing all features and components through a feature registry system.

2. Connection Management Layer: Handles incoming and outgoing connections through proxyman.InboundHandler and proxyman.OutboundHandler interfaces, with workers (tcpWorker, udpWorker) managing the actual socket operations.

3. Proxy Protocol Layer: Implements various proxy protocols (proxy/vless, proxy/wireguard, proxy/freedom, etc.) that encode/decode traffic according to their specifications.

4. Traffic Management Layer: The app/dispatcher coordinates routing decisions with app/router, performs DNS lookups via app/dns, and collects statistics through app/stats.

5. Transport Layer: Provides security and obfuscation through transport/internet/tls, transport/internet/reality, and various other transport mechanisms, all using the internet.Dialer abstraction for network operations.

Sources: core/core.go1-44 proxy/wireguard/client.go48-78 proxy/wireguard/server.go26-72 transport/internet/reality/reality.go1-50

Key Capabilities

REALITY Protocol

REALITY is Xray's advanced anti-censorship transport protocol that provides TLS traffic obfuscation while appearing as legitimate HTTPS connections. The implementation includes:

• Post-quantum cryptography: Support for ML-KEM-768 (Module-Lattice Key Encapsulation Mechanism) for key exchange and ML-DSA-65 (Module-Lattice Digital Signature Algorithm) for certificate verification
• Traffic indistinguishability: Sessions appear as genuine TLS connections to real destinations, making deep packet inspection ineffective
• Spider obfuscation: Automated web crawling behavior to mimic real browser activity when verification fails

Diagram: REALITY Protocol Components

The REALITY client (UConn) establishes connections by:

1. Generating an authentication key through ECDH key exchange and HKDF derivation
2. Sealing the session ID with AES-GCM using the auth key
3. Verifying the server certificate using HMAC-SHA512 and optionally ML-DSA-65 signatures

If verification fails (indicating a potential MITM or redirection), the spider mechanism activates to mimic real browser behavior by crawling the destination website.

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

VLESS Protocol with XTLS Vision

VLESS is a lightweight proxy protocol designed for efficiency and flexibility. When combined with XTLS Vision, it provides:

• Zero-overhead proxying: Direct memory copy of TLS traffic without decryption
• Traffic state detection: Identifies different phases of TLS communication
• Splice optimization: Uses zero-copy kernel operations when possible
• Padding support: Adds configurable padding to resist traffic analysis

The VLESS protocol stack integrates with various transports (TLS, REALITY, SplitHTTP) and supports advanced flow control mechanisms.

Sources: README.md79-91

WireGuard Support

Xray-core includes full WireGuard protocol support as both client and server, enabling:

• Virtual tunnel interface: Uses gvisor to create a userspace network stack
• DNS resolution integration: Resolves WireGuard peer endpoints using Xray's DNS system
• Flexible routing: Routes WireGuard traffic through Xray's dispatcher for advanced routing rules

The WireGuard implementation in proxy/wireguard creates a virtual TUN interface using gvisor's netstack, allowing WireGuard to operate without kernel modules while benefiting from Xray's routing and DNS capabilities.

Sources: proxy/wireguard/client.go1-339 proxy/wireguard/server.go1-191

Key Dependencies and External Libraries

Xray-core relies on several critical external libraries to implement its functionality:

Dependency	Version	Purpose
github.com/cloudflare/circl	v1.6.2	Post-quantum cryptography (ML-KEM-768, ML-DSA-65)
github.com/xtls/reality	v0.0.0-20251014195629	REALITY protocol implementation
github.com/refraction-networking/utls	v1.8.1	TLS fingerprinting and client hello customization
github.com/quic-go/quic-go	v0.58.0	QUIC and HTTP/3 support
golang.zx2c4.com/wireguard	v0.0.0-20231211153847	WireGuard protocol implementation
gvisor.dev/gvisor	v0.0.0-20250428193742	Userspace network stack for WireGuard
github.com/miekg/dns	v1.1.69	DNS protocol handling
google.golang.org/grpc	v1.78.0	gRPC transport support
google.golang.org/protobuf	v1.36.11	Protocol buffer serialization

Sources: go.mod1-57 go.sum1-165

Build and Deployment Ecosystem

Xray-core supports an extensive range of platforms through its automated build system:

Diagram: Build and Deployment Pipeline

The build system includes:

• Asset management: Automated daily updates of GeoIP and GeoSite data from upstream sources, with SHA256 verification and caching
• Cross-compilation: Support for 30+ platform/architecture combinations including Linux, Windows, macOS, FreeBSD, OpenBSD, and Android
• Special builds: Windows 7 support using a patched Go toolchain to maintain compatibility with legacy systems
• Docker images: Multi-architecture container images supporting amd64, arm64, arm/v7, arm/v6, ppc64le, s390x, 386, riscv64, and loong64
• Reproducible builds: Controlled build flags (-trimpath, -buildvcs=false, -ldflags) for deterministic output

Sources: .github/workflows/release.yml1-255 .github/workflows/docker.yml1-134 .github/workflows/release-win7.yml1-149 .github/workflows/scheduled-assets-update.yml1-66 .github/workflows/test.yml1-62

Traffic Flow Overview

Understanding how traffic flows through Xray-core is essential for grasping the platform's operation:

Diagram: Traffic Flow Through Xray-core

The traffic flow follows these steps:

1. Connection Acceptance: A SystemListener accepts incoming connections and passes them to a worker (tcpWorker or udpWorker)
2. Session Setup: The worker creates a session context with metadata (inbound tag, source address, statistics hooks)
3. Protocol Processing: The inbound protocol handler (proxy.Inbound) decodes the protocol-specific header and extracts the destination
4. Routing Decision: The Dispatcher consults the Router to select an appropriate outbound handler based on routing rules
5. Outbound Connection: The outbound protocol handler (proxy.Outbound) establishes a connection to the target using the SystemDialer
6. Data Transfer: Bidirectional data flows through a link abstraction that connects the inbound and outbound connections

Sources: proxy/wireguard/client.go145-252 proxy/wireguard/server.go79-120

Configuration System Architecture

Xray-core uses a flexible configuration system that supports JSON, TOML, and YAML formats, with a multi-file override mechanism:

Diagram: Configuration Processing Pipeline

The configuration system processes input through multiple stages:

1. Input Parsing: Configuration files in JSON, TOML, or YAML are parsed into intermediate structures
2. Config Building: The infra/conf package converts human-readable config into structured types (InboundDetourConfig, OutboundDetourConfig, etc.)
3. Protobuf Conversion: Configuration structures are converted to protobuf messages for efficient serialization and validation
4. Runtime Instantiation: The core.Instance loads the protobuf config and instantiates all handlers and features

For detailed configuration documentation, see Configuration System.

Sources: go.mod1-34

Getting Started

To understand specific aspects of Xray-core in more detail:

• Core architecture and component design: See Core Architecture and Platform Design
• Version information and feature support: See Versioning and Core Features
• External dependencies: See Dependencies and External Libraries
• Configuration syntax and options: See Configuration System
• Security protocols (TLS, REALITY): See Transport and Security Layer
• Proxy protocol details (VLESS, WireGuard, Freedom): See Proxy Protocols
• Connection handling and workers: See Connection Management
• Routing rules and traffic dispatching: See Routing and Dispatching
• DNS resolution system: See DNS System
• Build instructions and deployment: See Build and Deployment

Statistics and Monitoring

Xray-core includes a built-in statistics system for monitoring traffic and connection metrics. The app/stats package provides:

• Counter system: Track bytes uploaded/downloaded per user, inbound, or outbound
• Channel system: Publisher-subscriber pattern for real-time statistics events
• Policy integration: Time-based limits and traffic quotas

The statistics system uses a Channel implementation that supports:

• Configurable buffer sizes
• Blocking or non-blocking publish modes
• Multiple concurrent subscribers
• Graceful cleanup on unsubscribe

Sources: app/stats/channel_test.go1-406

Platform Philosophy

Xray-core follows a unified platform approach where all components interact through well-defined interfaces:

• Feature abstraction: Major subsystems (DNS, routing, policy, statistics) are accessed through a feature registry
• Protocol independence: Proxy protocols implement common interfaces (proxy.Inbound, proxy.Outbound) regardless of their underlying mechanism
• Transport flexibility: Security and transport layers are decoupled, allowing any protocol to use any transport
• Extensibility: New protocols, transports, and features can be added without modifying core logic

This design philosophy enables Xray-core to support a wide variety of anti-censorship scenarios while maintaining code clarity and testability.

Sources: core/core.go1-44 README.md1-50