Open-Source Observability · kutovoys

xray-checker

Xray Checker is a Prometheus-compatible monitoring tool for proxy server availability across VLESS, VMess, Trojan, and Shadowsocks protocols. It provides real-time metrics, a REST API, and a web dashboard for tracking proxy health and uptime.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/kutovoys/xray-checker

844

GitHub stars

Forks

Primary language

AGPL-3.0

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	kutovoys/xray-checker
Owner	kutovoys
Primary language	Go
License	AGPL-3.0 — OSI-approved
Stars	844
Forks	76
Open issues	2
Latest release	v1.3.1 (2026-07-01)
Last updated	2026-07-01
Source	https://github.com/kutovoys/xray-checker

What xray-checker is

Written in Go, Xray Checker integrates with Xray Core to perform connection testing, exports Prometheus metrics, supports Pushgateway integration, and exposes OpenAPI-documented REST endpoints. It loads proxy configurations from URLs, share links, JSON files, or folders.

Quickstart

Get the xray-checker source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/kutovoys/xray-checker.git2cd xray-checker3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

VPN/Proxy Service Operators

Monitor multiple Xray proxy instances across VLESS, VMess, Trojan, and Shadowsocks with automatic subscription updates and real-time health metrics feeding into existing Prometheus stacks.

Multi-Protocol Proxy Uptime Monitoring

Track proxy availability and performance with a public status page, REST API endpoints for Uptime Kuma integration, and Prometheus metrics for alerting and dashboarding.

Infrastructure-as-Code Proxy Management

Deploy via Docker/Docker Compose with environment-based configuration, automatic geo-file management, and flexible config sources (URLs, share links, JSON files) for CI/CD integration.

Implementation considerations

AGPL-3.0 copyleft license requires all modifications and derivative works to be open-sourced and licensed under AGPL-3.0; must be reviewed by legal/compliance before deployment.
Xray Core dependency: must be deployed alongside or accessible to Xray Checker; ensure compatible Xray versions and protocol support (VLESS, VMess, Trojan, Shadowsocks).
Subscription URL configuration and base64/JSON parsing; validate and test proxy configuration sources (URLs, share links, JSON folders) before production rollout.
Prometheus + Pushgateway integration requires existing metrics infrastructure; no built-in alerting—rely on Prometheus AlertManager or downstream tools.
Docker/Compose deployment is primary; native binary builds available but require Go toolchain management; geo-file auto-management reduces manual setup overhead.

When to avoid it — and what to weigh

Not for Closed-Source or Commercial Proprietary Deployments — AGPL-3.0 requires source disclosure and derivative work licensing. Commercial use requires legal review; closed-source wrappers or modifications may trigger copyleft obligations.
Not for Non-Xray Proxy Ecosystems — Tightly coupled to Xray Core and its protocol support. Incompatible with other proxy frameworks (HAProxy, Nginx, Squid) unless extended significantly.
Not for Teams Without Go/DevOps Expertise — Requires understanding of Prometheus metrics, Xray configuration, Docker orchestration, and AGPL licensing compliance. Limited for plug-and-play deployments without technical overhead.
Not for High-Touch Commercial Support Needs — Community-driven project with no SLA or commercial support contract. Telegram chat and GitHub issues are primary support channels; production critical deployments should assess risk.

License & commercial use

Licensed under AGPL-3.0 (GNU Affero General Public License v3.0). This is a copyleft license requiring all derivative works, modifications, and network-exposed deployments to be open-sourced under the same AGPL-3.0 terms.

AGPL-3.0 is not a permissive license. Commercial use is legally permissible but requires: (1) source disclosure of any modifications, (2) licensing of derived works under AGPL-3.0, and (3) network access provisions if exposed over internet. Closed-source commercial deployments or proprietary wrappers are not compliant. Legal review strongly recommended before commercial adoption.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

Basic Auth is supported for metrics and web UI but no advanced authentication (OAuth, LDAP). Network security depends on HTTPS proxy and firewall rules; no WAF or DDoS protection. Xray Core security posture not detailed here. AGPL-3.0 requires source code disclosure; ensure internal deployments do not expose proprietary logic. No explicit security audit or vulnerability disclosure policy mentioned; check GitHub security tab.

Alternatives to consider

Prometheus Node Exporter + Custom Scripts

Lower-level approach; monitor proxy uptime via shell scripts and standard node metrics. Requires more manual configuration but no copyleft licensing constraints.

Uptime Kuma (standalone)

Lighter-weight uptime monitoring tool with web UI and alerting, but lacks Prometheus-native metrics and Xray-specific protocol testing without custom integrations.

Grafana OnCall + Custom Exporters

Enterprise-grade alternative; decoupled alerting and dashboarding with support contracts. Higher cost but no licensing complications for commercial deployments.

Software development agency

Build on xray-checker with DEV.co software developers

Xray Checker offers strong uptime monitoring for Xray-based proxies with Prometheus integration. Before adopting, confirm AGPL-3.0 compliance with legal/compliance teams and validate Xray Core version compatibility with your infrastructure. Consider community support and maintenance dependencies for production use.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

kuberhealthy monitoror pyrra

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Observability DevOps & Infrastructure API Development & Integration Cloud Deployment & Containerization Talk to DEV.co

xray-checker FAQ

Can I use Xray Checker in a closed-source commercial product?

No, not without legal review and source disclosure. AGPL-3.0 requires all modifications and network-accessible deployments to be open-sourced under AGPL-3.0. Consult legal/compliance before commercial use.

Does Xray Checker support protocols other than VLESS, VMess, Trojan, and Shadowsocks?

Not out-of-the-box. Support depends on Xray Core capabilities; other protocols would require Xray Core patches and Xray Checker modifications, both of which trigger AGPL-3.0 disclosure requirements.

What happens if the maintainer stops development?

The project is open-source; the community can fork and maintain it. However, no SLA or commercial support is guaranteed. Assess fork stability and community activity before relying on production deployments.

Is Prometheus integration required, or can I use the REST API only?

Not required. The REST API with OpenAPI docs allows standalone integration with other monitoring systems (e.g., Uptime Kuma, custom dashboards). Prometheus is optional.

Work with a software development agency

DEV.co helps companies turn open-source tools like xray-checker into production software. Our software development services cover the full lifecycle — architecture, web development, integration, and maintenance — delivered by software developers and web developers who ship. Engage our software development agency to implement or customize it for your open-source observability stack.

Evaluate Xray Checker for Your Proxy Infrastructure

Talk to DEV.co Schedule a Consultation