Xray-core is a unified network proxy platform designed for anti-censorship and secure communication. It provides a modular framework to accept incoming network connections through various protocols (inbounds), process and route data internally, and forward traffic through diverse outbound protocols. core/core.go3-9
The platform serves as the foundation for the Project X ecosystem, supporting advanced security features like XTLS Vision, REALITY, and post-quantum encryption (ML-DSA-65). README.md1-3 README.md32 transport/internet/reality/reality.go24
Xray-core is organized as a modular platform where features are registered at compile-time and instantiated at runtime based on configuration. The entry point is the core package, which defines the platform's version and identity. core/core.go10-30
The following diagram bridges natural language components to the specific code entities that implement them, highlighting the initialization and registration flow.
Sources: core/core.go21-24 main/run.go212-226 core/config.go109-160
The version is tracked via Version_x, Version_y, and Version_z. core/core.go21-24 Currently, these represent version 26.4.25. core/core.go21-23
For details on the internal component interactions and the feature registry, see Core Architecture and Components.
Xray-core supports multiple configuration formats including JSON, YAML, TOML, and Protobuf. core/config.go82-95 The system uses a ConfigLoader pattern to transform external formats into the internal core.Config Protobuf message. core/config.go28-29 core/config.pb.go1-4
Sources: core/config.go16-42 core/config.go82-95 main/run.go132-143
The startXray function in the main execution path handles the transition from file paths to a running server instance. main/run.go212-226
Proxy protocols are modularly integrated. Inbound handlers manage incoming traffic, while outbound handlers govern how data leaves the system.
| Protocol / Feature | Category | Implementation / Role | Source |
|---|---|---|---|
| VLESS | Protocol | Modern proxy protocol; supports XTLS Vision | README.md30 |
| REALITY | Transport | TLS camouflage; uses UClient for fingerprinting | transport/internet/reality/reality.go117 |
| WireGuard | Protocol | Integrated via gvisor for user-space TUN | proxy/wireguard/tun.go145-147 |
| XTLS | Security | Enhanced TLS with splice and vision capabilities | README.md3 |
Sources: transport/internet/reality/reality.go117-176 proxy/wireguard/tun.go145-207 README.md85-87
Xray-core's lifecycle is managed with Go 1.26+. go.mod1-3 It relies on several key external libraries to provide its advanced networking capabilities.
Key Dependencies:
github.com/refraction-networking/utls for mimicking browser TLS signatures. go.mod16github.com/xtls/reality for the core REALITY implementation. go.mod22github.com/apernet/quic-go for Hysteria and QUIC transports. go.mod6github.com/cloudflare/circl for ML-DSA-65 verification in REALITY. go.mod7 transport/internet/reality/reality.go24gvisor.dev/gvisor for internal TUN/TAP handling. go.mod34For details on dependency integration, see Version Management and Dependencies.
Sources: go.mod5-37 transport/internet/reality/reality.go76-102
The project uses a sophisticated GitHub Actions CI/CD pipeline to support a vast matrix of operating systems and architectures. .github/workflows/release.yml79-161
Sources: .github/workflows/release.yml82-160 .github/workflows/release-win7.yml65-75 .github/workflows/docker.yml83-111
The build process includes specific handling for Android NDK .github/workflows/release.yml173-185 and a custom patched Go environment for Windows 7 support. .github/workflows/release-win7.yml98-106
Xray-core is the engine behind a large ecosystem of GUI clients and management panels. For a detailed list, see Ecosystem and Distribution.
ghcr.io/xtls/xray-core. README.md58