Xray Checker is an AGPL-3.0-licensed tool written in Go that tests real connections through Xray Core to monitor proxy server availability across the VLESS, VMess, Trojan and Shadowsocks protocols, then exposes the results as Prometheus metrics and REST API endpoints for operators of self-hosted proxy and VPN services.

What it is

Xray Checker is a monitoring exporter for Xray-based proxy infrastructure. It runs as its own process or container, speaks the proxy protocols directly through Xray Core, and turns the outcome of those tests into metrics that a Prometheus-compatible monitoring stack can scrape. Alongside the metrics endpoint on port 2112 it ships a REST API documented with OpenAPI/Swagger, a web interface with dark and light themes, and a public status page. The project is written in Go, licensed AGPL-3.0, carries 904 stars and 88 forks with 20 open issues, and the repository was last pushed on 10 September 2026. Documentation lives at xray-checker.kutovoy.dev, and the README exists in both English and Russian.

The problem it solves is the failure mode of proxy and VPN nodes: a server can stay pingable and answer on its port while the tunnel behind it is broken, so generic uptime checks report green on a node that no client can actually use. Xray Checker closes that gap by performing genuine connection tests per protocol and per node, which is work an operator would otherwise do by hand or with purpose-built scripts. It lives in the Prometheus and observability ecosystem and in the operational tooling around proxy panels such as Marzban and Remnawave, both of which appear in its topics. It complements rather than replaces general uptime monitors, because the README lists endpoints for integration with systems such as Uptime Kuma, which receive the verdicts Xray Checker produces.

Key capabilities

• Tests proxy availability over VLESS, VMess, Trojan and Shadowsocks, running each connection through Xray Core.
• Exports Prometheus metrics, including Pushgateway support, on port 2112.
• Serves a REST API with OpenAPI/Swagger documentation for integration into monitoring systems.
• Provides a web interface with dark and light themes and full customization, down to a custom logo, custom styles, or an entirely replaced template.
• Publishes a public status page for VPN services that requires no authentication, and protects the metrics and the web interface with Basic Auth.
• Loads configuration from subscription URLs in base64 and JSON form, share links (vless://, vmess://, trojan://, ss://), JSON configuration files, and folders of configurations, with multiple subscriptions supported and automatic configuration updates.
• Manages geo files (geoip.dat, geosite.dat) automatically, and ships as a Docker image with Docker Compose support.

Who uses it and how

• Operators running self-hosted proxy services, particularly around the Marzban and Remnawave panels named in the project topics, use it to track which nodes still carry working connections.
• Teams already running Prometheus scrape the metrics endpoint directly, or push into a Pushgateway when the checker itself cannot be scraped.
• Services that want to show customers which locations are up deploy the unauthenticated public status page, while keeping metrics and the web interface behind Basic Auth.
• Monitoring stacks that prefer HTTP over scraping call the REST API, documented with OpenAPI/Swagger, or use the endpoints intended for tools such as Uptime Kuma.
• Smaller deployments run it as a single container with Docker Compose, pointing the SUBSCRIPTION_URL environment variable at a subscription and exposing port 2112.

Getting started

Run the container with docker run -d -e SUBSCRIPTION_URL=https://your-subscription-url/sub -p 2112:2112 kutovoys/xray-checker, or use the equivalent Docker Compose service that sets image to kutovoys/xray-checker and the same environment variable. Full installation and configuration documentation is at xray-checker.kutovoy.dev, and a live demo runs at demo-xray-checker.kutovoy.dev.

How it compares

No comparable tool is named in the facts and no list of paid products it replaces is supplied, so it stands alone in this registry as the Prometheus exporter built specifically for Xray proxy monitoring. Its topics place it in the same operational neighbourhood as Marzban and Remnawave, but those are proxy panels rather than monitoring exporters, so no head-to-head substitution is documented.

When to use it — and when not to

Choose it when the estate is Xray-based and the monitoring stack is Prometheus-shaped, because it then reports on connections that the rest of the stack cannot test. A self-hoster must run the container with network access to every monitored node and supply at least one subscription URL or other configuration source, and the AGPL-3.0 licence is worth checking before embedding it inside a closed product. The README excerpt is thin and defers most detail to the external documentation site, so anyone needing advanced configuration should expect to read xray-checker.kutovoy.dev rather than the repository alone.

docker run -d \
  -e SUBSCRIPTION_URL=https://your-subscription-url/sub \
  -p 2112:2112 \
  kutovoys/xray-checker

services:
  xray-checker:
    image: kutovoys/xray-checker
    environment:
      - SUBSCRIPTION_URL=https://your-subscription-url/sub
    ports:
      - "2112:2112"