libXray

WARNING

Use only one Go runtime per process.

Every native libXray artifact (whether produced via cgo or gomobile) embeds a Go runtime. Do not load libXray alongside any other independently built Go, cgo, or gomobile library in the same executable or process. Doing so will cause build, link, or load failures, or runtime crashes during initialization.

Correct Pattern: If your process needs Go packages from multiple libraries, include them in a single Go build or gomobile bind invocation to produce one native artifact that shares a single runtime.

WARNING

Each process can only use one Go runtime.

Go does not support loading multiple independent Go runtimes within the same process. Since all libXray products embed a Go runtime (via cgo or gomobile), you must not load libXray and another independent Go/cgo/gomobile library in the same executable or process. Doing so will cause failures during building, linking, loading, or runtime initialization.

Solution: If you need multiple Go packages in one process, they must be included in a single Go build or gomobile bind command so they share a single runtime. Simply re-packaging or merging existing frameworks, archives, AARs, or DLLs will not work.

libXray uses CalVer for releases (e.g., v26.3.27), but Go modules require a SemVer-compatible import path. To install a specific version, use the mirrored SemVer tag (e.g., v1.260327.0 for release v26.3.27).

Always pin against the SemVer mirror to ensure compatibility with Go's module system.

go get github.com/xtls/libxray@v1.260327.0

To prevent Android VPN runtimes from providing loopback DNS addresses to the Go resolver, use the controller API to set a specific DNS and protect the socket.

1. Call LibXray.setDNS(controller, "<IP:port>") before runXray.
2. The DNS must be an IP endpoint with a port (e.g., 8.8.8.8:53 or [2001:4860:4860::8888]:53).
3. After stopping the core, call LibXray.resetDNS().

Note: These APIs are only available in Android builds and modify the Go process-level default resolver.

// Android usage pattern
LibXray.setDNS(controller, "8.8.8.8:53");
LibXray.invoke(runXrayRequest);

// Later, when stopping the Core:
LibXray.invoke(stopXrayRequest);
LibXray.resetDNS();

libXray does not sample or save traffic data itself. Instead, the application should read metrics directly from the Xray instance's built-in HTTP API.

Setup Requirements:

1. The Xray configuration must include a metrics object with a listen address.
2. The Xray configuration must enable statistics in the policy.system section.

How to access: Once Xray is running, use an HTTP client to query the /debug/vars endpoint at the specified listen address.

Example Configuration:

{
  "metrics" : {
    "listen": "127.0.0.1:49227"
  },
  "policy" : {
    "system" : {
      "statsInboundDownlink" : true,
      "statsInboundUplink" : true,
      "statsOutboundDownlink" : true,
      "statsOutboundUplink" : true
    }
  }
}

Example Request: GET http://127.0.0.1:49227/debug/vars

http://localhost:49227/debug/vars

libXray uses a unified invocation pattern to execute various Xray-related tasks. All requests are structured using the LibXrayInvokeRequest type, which specifies the APIVersion, the Method to be called, and a Payload containing the method-specific data as a json.RawMessage.

// Conceptual structure of an invocation request
request := LibXrayInvokeRequest{
    APIVersion: LibXrayAPIVersion,
    Method:     LibXrayMethodRunXray,
    Payload:    jsonPayload, // json.RawMessage containing RunXrayRequest
}

libXray allows you to expose Xray runtime counters through an HTTP server. To enable this, include a metrics block in your Xray JSON configuration.

Configuration Example

To expose metrics on 127.0.0.1:49227 and enable outbound/inbound statistics, use the following structure:

{
  "metrics" : {
    "listen": "127.0.0.1:49227"
  },
  "policy" : {
    "system" : {
      "statsInboundDownlink" : true,
      "statsInboundUplink" : true,
      "statsOutboundDownlink" : true,
      "statsOutboundUplink" : true
    }
  },
  "stats" : {}
}

Accessing Data

Once the Xray instance is running, query the /debug/vars endpoint directly using an HTTP client: http://localhost:49227/debug/vars

To prevent Go's resolver from using a loopback DNS server exposed by a VPN, use the SetDNS and ResetDNS APIs available in the Android artifact. This protects the DNS socket from the VPN tunnel.

1. Call SetDNS with an IP endpoint and port (e.g., 8.8.8.8:53) before calling runXray.
2. Call ResetDNS after the Xray core has stopped.

// Set the DNS before running Xray
LibXray.setDNS(controller, "8.8.8.8:53");
LibXray.invoke(runXrayRequest);

// Later, when stopping the core:
LibXray.invoke(stopXrayRequest);
LibXray.resetDNS();