### Get System Information

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Returns version, uptime, and instance metadata. Requires authentication.

```APIDOC
## GET /api/v1/system/info

### Description
Returns version, uptime, and instance metadata.

### Method
GET

### Endpoint
/api/v1/system/info

### Parameters
#### Query Parameters
- **username** (string) - Required - Basic auth username
- **password** (string) - Required - Basic auth password

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - System information.
  - **version** (string) - The version of the checker.
  - **uptime** (string) - The uptime of the checker.
  - **uptimeSec** (integer) - The uptime in seconds.
  - **instance** (string) - The instance name or type.

### Response Example
{
  "success": true,
  "data": {
    "version": "1.0.0",
    "uptime": "1d 2h 30m 45s",
    "uptimeSec": 95445,
    "instance": "production"
  }
}
```

--------------------------------

### Basic Authentication Example

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/api-reference.md

Example of how to authenticate with protected endpoints using Basic Authentication via curl. Replace 'username' and 'password' with your credentials.

```bash
curl -u username:password http://localhost:2112/metrics
```

--------------------------------

### Nginx Server Block Example

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/advanced-conf.md

An example of a basic Nginx server block configuration, showing the root directory and server name.

```nginx
server {
    root /var/www/your-domain.com/html;

    index index.html;
    server_name your-stealing-domain.com;
    ...
}
```

--------------------------------

### Run xray-checker in Development Mode

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/contributing/guide.md

Start the application in development mode using the Go run command.

```bash
go run main.go
```

--------------------------------

### Configure Port Ranges

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/advanced-conf.md

Customize the starting port for SOCKS5 proxies and the port for metrics collection.

```bash
# Start SOCKS5 ports from 20000
XRAY_START_PORT=20000

# Change metrics port
METRICS_PORT=9090
```

--------------------------------

### Example: Light Theme CSS Override

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/web-customization.md

Customize the appearance for a light theme by overriding the default CSS variables. This example sets lighter background and text colors.

```css
:root {
  --bg-primary: #ffffff;
  --bg-secondary: #f8f9fa;
  --bg-tertiary: #e9ecef;
  --text-primary: #212529;
  --text-secondary: #495057;
  --text-muted: #6c757d;
  --border: #dee2e6;
}
```

--------------------------------

### Custom CSS Example for Web UI

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Example of a custom CSS file to override default Xray Checker web UI styles. Demonstrates changing theme colors and styling proxy status indicators.

```css
/* custom.css - Override default styles */
:root {
  --primary-color: #007bff;
  --background-dark: #1a1a2e;
  --background-light: #ffffff;
}

.proxy-card.online {
  border-left: 4px solid #28a745;
}

.proxy-card.offline {
  border-left: 4px solid #dc3545;
}

.latency-badge {
  font-family: monospace;
  padding: 2px 8px;
  border-radius: 4px;
}
```

--------------------------------

### Docker Quick Start: Multiple Subscriptions and Customization

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Deploy Xray Checker with multiple subscription URLs, custom check interval, and check method. Ensure port 2112 is exposed.

```bash
docker run -d \
  -e SUBSCRIPTION_URL="https://sub1.example.com/sub,https://sub2.example.com/sub" \
  -e PROXY_CHECK_INTERVAL=300 \
  -e PROXY_CHECK_METHOD=ip \
  -p 2112:2112 \
  kutovoys/xray-checker
```

--------------------------------

### Change Server Start Port

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/troubleshooting.md

If Xray Checker fails to start due to a port conflict, adjust the starting port for SOCKS proxies using the XRAY_START_PORT environment variable.

```bash
XRAY_START_PORT=20000
```

--------------------------------

### Prometheus Scrape Configuration

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/api-reference.md

Example Prometheus scrape configuration to monitor Xray Checker metrics. Includes basic authentication setup.

```yaml
scrape_configs:
  - job_name: "xray-checker"
    metrics_path: "/metrics"
    basic_auth:
      username: "username"
      password: "password"
    static_configs:
      - targets: ["localhost:2112"]
```

--------------------------------

### Get All Proxies (Authenticated)

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Retrieves detailed information for all configured proxies. Requires authentication with admin credentials.

```bash
# Get all proxies with full details
curl -u admin:password http://localhost:2112/api/v1/proxies
```

```json
# Response
{
  "success": true,
  "data": [
    {
      "index": 0,
      "stableId": "a1b2c3d4e5f67890",
      "name": "US-Server-1",
      "subName": "Premium VPN",
      "server": "192.168.1.1",
      "port": 443,
      "protocol": "vless",
      "proxyPort": 10000,
      "online": true,
      "latencyMs": 150
    },
    {
      "index": 1,
      "stableId": "b2c3d4e5f6789012",
      "name": "EU-Server-2",
      "subName": "Premium VPN",
      "server": "10.0.0.1",
      "port": 443,
      "protocol": "vmess",
      "proxyPort": 10001,
      "online": false,
      "latencyMs": 0
    }
  ]
}
```

--------------------------------

### Get System Information (Authenticated)

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Retrieves system metadata including the checker version, uptime, and instance name. Requires authentication.

```bash
# Get system info
curl -u admin:password http://localhost:2112/api/v1/system/info
```

```json
# Response
{
  "success": true,
  "data": {
    "version": "1.0.0",
    "uptime": "1d 2h 30m 45s",
    "uptimeSec": 95445,
    "instance": "production"
  }
}
```

--------------------------------

### Full Xray Checker Configuration Example

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/cli.md

Demonstrates a comprehensive set of command-line arguments for configuring Xray Checker, covering subscription updates, proxy checks, metrics, and web interface settings.

```bash
./xray-checker \
  --subscription-url=https://your-subscription-url/sub \
  --subscription-update=true \
  --subscription-update-interval=300 \
  --proxy-check-interval=300 \
  --proxy-timeout=30 \
  --proxy-check-method=ip \
  --proxy-ip-check-url="https://api.ipify.org?format=text" \
  --proxy-status-check-url="http://cp.cloudflare.com/generate_204" \
  --proxy-download-url="https://proof.ovh.net/files/1Mb.dat" \
  --proxy-download-timeout=60 \
  --proxy-download-min-size=51200 \
  --proxy-resolve-domains=false \
  --simulate-latency=true \
  --xray-start-port=10000 \
  --xray-log-level=none \
  --metrics-host=0.0.0.0 \
  --metrics-port=2112 \
  --metrics-protected=true \
  --metrics-username=custom_user \
  --metrics-password=custom_pass \
  --metrics-instance=node-1 \
  --metrics-push-url="https://push.example.com" \
  --metrics-base-path="/xray/monitor" \
  --web-show-details=false \
  --web-public=false \
  --log-level=info \
  --run-once=false
```

--------------------------------

### Docker Quick Start: Authentication and Public Status

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Deploy Xray Checker with subscription URL, enable protected metrics with authentication, and activate the public status page. Ensure port 2112 is exposed.

```bash
docker run -d \
  -e SUBSCRIPTION_URL=https://your-subscription-url/sub \
  -e METRICS_PROTECTED=true \
  -e METRICS_USERNAME=admin \
  -e METRICS_PASSWORD=securepassword \
  -e WEB_PUBLIC=true \
  -p 2112:2112 \
  kutovoys/xray-checker
```

--------------------------------

### Environment Variables: Xray Configuration

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Configure Xray Core settings, including the starting port for proxy configurations and the log level.

```bash
# Xray Configuration
XRAY_START_PORT=10000                          # Starting port for proxy configs (default: 10000)
XRAY_LOG_LEVEL=none                            # Xray log level: debug|info|warning|error|none
```

--------------------------------

### Minimal HTML Template Example

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/web-customization.md

A basic HTML structure for displaying proxy status information. Includes conditional rendering for subscription names and proxy status indicators.

```html
<!DOCTYPE html>
<html>
<head>
  <title>{{ if .SubscriptionName }}{{ .SubscriptionName }}{{ else }}Status{{ end }}</title>
</head>
<body>
  <h1>Proxy Status</h1>
  {{ range .Endpoints }}
  <div>
    {{ if .Status }}✓{{ else }}✗{{ end }}
    {{ .Name }}
    ({{ formatLatency .Latency }})
  </div>
  {{ end }}
</body>
</html>
```

--------------------------------

### Recommended Debug Logging Setup

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/troubleshooting.md

For effective troubleshooting, enable application debug logging and Xray core warning logging. This provides detailed application logs while keeping Xray output manageable.

```bash
LOG_LEVEL=debug
XRAY_LOG_LEVEL=warning
```

--------------------------------

### Get All Proxies (Authenticated)

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Retrieves detailed information about all configured proxies. Requires authentication.

```APIDOC
## GET /api/v1/proxies

### Description
Returns detailed information about all configured proxies including server addresses and ports.

### Method
GET

### Endpoint
/api/v1/proxies

### Parameters
#### Query Parameters
- **username** (string) - Required - Basic auth username
- **password** (string) - Required - Basic auth password

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - An array of proxy objects.
  - **index** (integer) - The index of the proxy.
  - **stableId** (string) - The stable identifier for the proxy.
  - **name** (string) - The name of the proxy server.
  - **subName** (string) - The sub-name or type of the proxy.
  - **server** (string) - The server address.
  - **port** (integer) - The server port.
  - **protocol** (string) - The protocol used by the proxy.
  - **proxyPort** (integer) - The proxy port.
  - **online** (boolean) - Indicates if the proxy is currently online.
  - **latencyMs** (integer) - The latency in milliseconds.

### Response Example
{
  "success": true,
  "data": [
    {
      "index": 0,
      "stableId": "a1b2c3d4e5f67890",
      "name": "US-Server-1",
      "subName": "Premium VPN",
      "server": "192.168.1.1",
      "port": 443,
      "protocol": "vless",
      "proxyPort": 10000,
      "online": true,
      "latencyMs": 150
    }
  ]
}
```

--------------------------------

### Get System Status Summary

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Returns aggregate statistics about all monitored proxies. Requires authentication.

```APIDOC
## GET /api/v1/status

### Description
Returns aggregate statistics about all monitored proxies.

### Method
GET

### Endpoint
/api/v1/status

### Parameters
#### Query Parameters
- **username** (string) - Required - Basic auth username
- **password** (string) - Required - Basic auth password

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - The status summary.
  - **total** (integer) - Total number of proxies.
  - **online** (integer) - Number of online proxies.
  - **offline** (integer) - Number of offline proxies.
  - **avgLatencyMs** (integer) - Average latency in milliseconds.

### Response Example
{
  "success": true,
  "data": {
    "total": 10,
    "online": 8,
    "offline": 2,
    "avgLatencyMs": 200
  }
}
```

--------------------------------

### Get System Version and Uptime

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/api-reference.md

Retrieves version and uptime information for the Xray Checker instance. Requires authentication if METRICS_PROTECTED is true.

```http
GET /api/v1/system/info
```

```json
{
  "success": true,
  "data": {
    "version": "1.0.0",
    "uptime": "1h 30m 45s",
    "uptimeSec": 5445,
    "instance": "prod-1"
  }
}
```

--------------------------------

### Install Xray Checker for Linux arm64

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/cli.md

Download and extract the latest Xray Checker binary for Linux arm64. Ensure the binary is executable after extraction.

```bash
curl -sL -o - $(curl -s https://api.github.com/repos/kutovoys/xray-checker/releases/latest | grep "browser_download_url.*linux-arm64.tar.gz" | cut -d'"' -f4) | tar -xz
chmod +x xray-checker
```

--------------------------------

### Basic Uptime Kuma Monitor Setup

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/integrations/uptime-kuma.md

Use this URL format for basic HTTP(s) monitoring of a proxy status endpoint in Uptime Kuma. Ensure the token is correct for the proxy you wish to monitor.

```text
http://localhost:2112/config/a1b2c3d4e5f67890
```

--------------------------------

### Install Xray Checker for Linux amd64

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/cli.md

Download and extract the latest Xray Checker binary for Linux amd64. Ensure the binary is executable after extraction.

```bash
curl -sL -o - $(curl -s https://api.github.com/repos/kutovoys/xray-checker/releases/latest | grep "browser_download_url.*linux-amd64.tar.gz" | cut -d'"' -f4) | tar -xz
chmod +x xray-checker
```

--------------------------------

### Get Current Configuration (Authenticated)

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Returns the current active configuration settings of the Xray-Checker. Requires authentication.

```bash
# Get configuration
curl -u admin:password http://localhost:2112/api/v1/config
```

```json
# Response
{
  "success": true,
  "data": {
    "checkInterval": 300,
    "checkMethod": "ip",
    "timeout": 30,
    "startPort": 10000,
    "subscriptionUpdate": true,
    "subscriptionUpdateInterval": 300,
    "simulateLatency": true,
    "subscriptionNames": ["Premium VPN", "Basic VPN"]
  }
}
```

--------------------------------

### Check Xray Checker Version

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/intro/quick-start.md

Displays the currently installed version of the Xray Checker binary.

```bash
./xray-checker --version
```

--------------------------------

### Run Xray Checker with Multiple Subscriptions via CLI Arguments

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/docker.md

An alternative method to specify multiple subscription URLs using repeated CLI arguments for a cleaner setup.

```bash
docker run -d \
  -p 2112:2112 \
  kutovoys/xray-checker \
  --subscription-url=https://provider1.com/sub \
  --subscription-url=https://provider2.com/sub
```

--------------------------------

### Common Astro Project Commands

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/README.md

A list of essential commands for managing your Astro project. These commands cover dependency installation, local development, building for production, and previewing the build.

```bash
npm install
```

```bash
npm run dev
```

```bash
npm run build
```

```bash
npm run preview
```

```bash
npm run astro ...
```

```bash
npm run astro -- --help
```

--------------------------------

### Install Xray Checker for macOS (Intel)

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/cli.md

Download and extract the latest Xray Checker binary for macOS on Intel processors. Ensure the binary is executable after extraction.

```bash
curl -sL -o - $(curl -s https://api.github.com/repos/kutovoys/xray-checker/releases/latest | grep "browser_download_url.*darwin-amd64.tar.gz" | cut -d'"' -f4) | tar -xz
chmod +x xray-checker
```

--------------------------------

### Uptime Kuma Monitor Setup with Basic Auth

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/integrations/uptime-kuma.md

Configure Uptime Kuma with Basic Authentication for monitoring a proxy status endpoint when metrics protection is enabled. Provide your METRICS_USERNAME and METRICS_PASSWORD.

```text
http://username:password@localhost:2112/config/a1b2c3d4e5f67890
```

--------------------------------

### Docker Compose Configuration

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/web-customization.md

Example Docker Compose configuration for running the Xray Checker service. Includes volume mounting for custom assets and environment variables for configuration.

```yaml
services:
  xray-checker:
    image: kutovoys/xray-checker:latest
    volumes:
      - ./custom:/app/custom:ro
    environment:
      - WEB_CUSTOM_ASSETS_PATH=/app/custom
      - SUBSCRIPTION_URL=https://...
```

--------------------------------

### Get Single Proxy by Stable ID (Authenticated)

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Fetches detailed information for a specific proxy using its unique stable ID. Requires authentication.

```bash
# Get specific proxy by stable ID
curl -u admin:password http://localhost:2112/api/v1/proxies/a1b2c3d4e5f67890
```

```json
# Response
{
  "success": true,
  "data": {
    "index": 0,
    "stableId": "a1b2c3d4e5f67890",
    "name": "US-Server-1",
    "subName": "Premium VPN",
    "server": "192.168.1.1",
    "port": 443,
    "protocol": "vless",
    "proxyPort": 10000,
    "online": true,
    "latencyMs": 150
  }
}
```

```json
# Error response (proxy not found)
{
  "success": false,
  "error": "Proxy not found"
}
```

--------------------------------

### Change Ports for Metrics and Xray

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/cli.md

Customize the host and port for the metrics endpoint, and the starting port for Xray instances. Useful for avoiding port conflicts.

```bash
./xray-checker \
  --subscription-url=https://your-sub-url \
  --metrics-host=127.0.0.1 \
  --metrics-port=3000 \
  --xray-start-port=20000
```

--------------------------------

### Get System Status Summary (Authenticated)

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Retrieves an aggregate summary of all monitored proxies, including total, online, offline counts, and average latency. Requires authentication.

```bash
# Get overall status summary
curl -u admin:password http://localhost:2112/api/v1/status
```

```json
# Response
{
  "success": true,
  "data": {
    "total": 10,
    "online": 8,
    "offline": 2,
    "avgLatencyMs": 200
  }
}
```

--------------------------------

### Startup Logs with Custom Assets

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/web-customization.md

Illustrates the expected log output when custom assets are successfully loaded, both with and without a custom template. Verifies asset loading and template usage.

```log
INFO  Custom assets enabled: /app/custom
INFO  Custom assets loaded:
INFO    ✓ logo.svg
INFO    ✓ custom.css
INFO  Using default template
```

```log
INFO  Custom assets loaded:
INFO    ✓ index.html
INFO    ✓ custom.css
INFO  Using custom template: index.html
```

--------------------------------

### Install Xray Checker for macOS (Apple Silicon)

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/cli.md

Download and extract the latest Xray Checker binary for macOS on Apple Silicon (M1/M2/etc.) processors. Ensure the binary is executable after extraction.

```bash
curl -sL -o - $(curl -s https://api.github.com/repos/kutovoys/xray-checker/releases/latest | grep "browser_download_url.*darwin-arm64.tar.gz" | cut -d'"' -f4) | tar -xz
chmod +x xray-checker
```

--------------------------------

### Start Countdown Timer

Source: https://github.com/kutovoys/xray-checker/blob/main/web/templates/index.html

Initializes and starts a countdown interval. Refreshes data when the countdown reaches zero.

```javascript
startCountdown() {
  this.countdown = {{ .CheckInterval }};
  this.countdownInterval = setInterval(() => {
    if (--this.countdown <= 0) this.refreshData();
  }, 1000);
}
```

--------------------------------

### Xray Proxy Latency Metric Example

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/integrations/metrics.md

This metric shows the connection response time in milliseconds. It shares the same labels as the xray_proxy_status metric. A value of 0 indicates a failed connection.

```text
# HELP xray_proxy_latency_ms Latency of proxy connection in milliseconds
# TYPE xray_proxy_latency_ms gauge
xray_proxy_latency_ms{protocol="vless",address="example.com:443",name="proxy1",sub_name="Premium VPN",instance="dc1"} 156
```

--------------------------------

### Docker Compose Deployment

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Deploy Xray Checker using Docker Compose, configuring subscription, check intervals, timeouts, updates, authentication, and logging. Optionally includes Prometheus setup.

```yaml
version: '3.8' 
services:
  xray-checker:
    image: kutovoys/xray-checker
    container_name: xray-checker
    environment:
      - SUBSCRIPTION_URL=https://your-subscription-url/sub
      - PROXY_CHECK_INTERVAL=300
      - PROXY_CHECK_METHOD=ip
      - PROXY_TIMEOUT=30
      - SUBSCRIPTION_UPDATE=true
      - SUBSCRIPTION_UPDATE_INTERVAL=300
      - METRICS_PROTECTED=true
      - METRICS_USERNAME=admin
      - METRICS_PASSWORD=securepassword
      - METRICS_INSTANCE=production
      - LOG_LEVEL=info
    ports:
      - "2112:2112"
    restart: unless-stopped

  # Optional: Prometheus for metrics collection
  prometheus:
    image: prom/prometheus
    volumes: 
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"
```

--------------------------------

### Xray Proxy Status Metric Example

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/integrations/metrics.md

This metric indicates proxy availability. It uses labels for protocol, address, name, sub_name, and instance. A value of 1 means the proxy is working, and 0 means it has failed.

```text
# HELP xray_proxy_status Status of proxy connection (1: success, 0: failure)
# TYPE xray_proxy_status gauge
xray_proxy_status{protocol="vless",address="example.com:443",name="proxy1",sub_name="Premium VPN",instance="dc1"} 1
```

--------------------------------

### Download Go Dependencies

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/contributing/guide.md

Download all the necessary Go modules for the project.

```bash
go mod download
```

--------------------------------

### Set Subscription URL

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/subscription.md

Use the SUBSCRIPTION_URL environment variable to specify the proxy subscription source. This example shows the default format, a standard HTTPS URL returning Base64 encoded proxy links.

```bash
SUBSCRIPTION_URL=https://example.com/subscription
```

--------------------------------

### Supported Share Link Formats

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Examples of various proxy protocol share link formats including VLESS, VMess, Trojan, and Shadowsocks. VMess links are typically base64 encoded JSON.

```bash
# VLESS
vless://uuid@server:port?security=tls&type=ws&path=/path&host=example.com#Name

# VMess (base64 encoded JSON)
vmess://eyJhZGQiOiJzZXJ2ZXIiLCJwb3J0Ijo0NDMsInR5cGUiOiJub25lIiwiaWQiOiJ1dWlkIn0=

# Trojan
trojan://password@server:port?security=tls&sni=example.com#Name

# Shadowsocks
ss://method:password@server:port#Name
```

--------------------------------

### Set Up Test Subscription URL

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/contributing/guide.md

Configure the subscription URL for local testing.

```bash
export SUBSCRIPTION_URL=your_test_subscription
```

--------------------------------

### Get Current Configuration

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Returns the current checker configuration settings. Requires authentication.

```APIDOC
## GET /api/v1/config

### Description
Returns the current checker configuration settings.

### Method
GET

### Endpoint
/api/v1/config

### Parameters
#### Query Parameters
- **username** (string) - Required - Basic auth username
- **password** (string) - Required - Basic auth password

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - The configuration settings.
  - **checkInterval** (integer) - Interval in seconds for checking proxies.
  - **checkMethod** (string) - Method used for checking proxies.
  - **timeout** (integer) - Timeout in seconds for proxy checks.
  - **startPort** (integer) - The starting port for proxy checks.
  - **subscriptionUpdate** (boolean) - Whether to update subscriptions.
  - **subscriptionUpdateInterval** (integer) - Interval in seconds for subscription updates.
  - **simulateLatency** (boolean) - Whether to simulate latency.
  - **subscriptionNames** (array) - List of subscription names.

### Response Example
{
  "success": true,
  "data": {
    "checkInterval": 300,
    "checkMethod": "ip",
    "timeout": 30,
    "startPort": 10000,
    "subscriptionUpdate": true,
    "subscriptionUpdateInterval": 300,
    "simulateLatency": true,
    "subscriptionNames": ["Premium VPN", "Basic VPN"]
  }
}
```

--------------------------------

### Build xray-checker Project

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/contributing/guide.md

Build the project using either the Makefile or directly with the Go build command.

```bash
make build
```

```bash
go build -o xray-checker
```

--------------------------------

### Create a New Starlight Project

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/README.md

Use this command to create a new Astro project with the Starlight template. This is the initial step for setting up your documentation site.

```bash
npm create astro@latest -- --template starlight
```

--------------------------------

### Get Proxy by ID

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/api-reference.md

Retrieves detailed information for a specific proxy using its stable ID.

```APIDOC
## GET /api/v1/proxies/{stableId}

### Description
Returns information for a specific proxy.

### Method
GET

### Endpoint
/api/v1/proxies/{stableId}

### Parameters
#### Path Parameters
- **stableId** (string) - Required - The 16-character stable identifier hash for the proxy.

### Response
#### Success Response (200)
- Returns the same structure as a single item from the `/api/v1/proxies` endpoint.

### Note
This endpoint requires authentication if `METRICS_PROTECTED` is set to `true`.
```

--------------------------------

### Get OpenAPI Specification

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/api-reference.md

Retrieves the OpenAPI specification file in YAML format. This endpoint is public.

```http
GET /api/v1/openapi.yaml
```

--------------------------------

### Folder Subscription with JSON Configs

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Provide a folder path using the 'folder://' prefix to load multiple Xray configuration files. Each JSON file should adhere to the specified format.

```bash
# Folder containing multiple JSON config files
SUBSCRIPTION_URL="folder:///app/configs/"

# Each JSON file should have the Xray config format:
# {
#   "remarks": "Server Name",
#   "outbounds": [...]
# }
```

--------------------------------

### CLI Usage: Basic Options

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Run Xray Checker from the command line with basic options for subscription URL, check interval, and check method.

```bash
xray-checker \
  --subscription-url=https://your-subscription-url/sub \
  --proxy-check-interval=300 \
  --proxy-check-method=ip
```

--------------------------------

### Environment Variables: Subscription Configuration

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Configure subscription sources and update intervals. SUBSCRIPTION_URL is required and can accept multiple URLs separated by commas. SUBSCRIPTION_UPDATE defaults to true.

```bash
# Subscription Configuration
SUBSCRIPTION_URL=https://example.com/sub      # Required: URL(s) for proxy subscription (comma-separated for multiple)
SUBSCRIPTION_UPDATE=true                       # Enable automatic subscription updates (default: true)
SUBSCRIPTION_UPDATE_INTERVAL=300               # Update interval in seconds (default: 300)
```

--------------------------------

### Full Docker Configuration for Xray Checker

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/docker.md

Demonstrates running Xray Checker with a comprehensive set of environment variables to control subscriptions, updates, proxy checks, metrics, and web interface settings.

```bash
docker run -d \
  -e SUBSCRIPTION_URL=https://your-subscription-url/sub \
  -e SUBSCRIPTION_UPDATE=true \
  -e SUBSCRIPTION_UPDATE_INTERVAL=300 \
  -e PROXY_CHECK_INTERVAL=300 \
  -e PROXY_CHECK_METHOD=ip \
  -e PROXY_TIMEOUT=30 \
  -e PROXY_IP_CHECK_URL=https://api.ipify.org?format=text \
  -e PROXY_STATUS_CHECK_URL=http://cp.cloudflare.com/generate_204 \
  -e PROXY_DOWNLOAD_URL=https://proof.ovh.net/files/1Mb.dat \
  -e PROXY_DOWNLOAD_TIMEOUT=60 \
  -e PROXY_DOWNLOAD_MIN_SIZE=51200 \
  -e PROXY_RESOLVE_DOMAINS=false \
  -e SIMULATE_LATENCY=true \
  -e XRAY_START_PORT=10000 \
  -e XRAY_LOG_LEVEL=none \
  -e METRICS_HOST=0.0.0.0 \
  -e METRICS_PORT=2112 \
  -e METRICS_PROTECTED=true \
  -e METRICS_USERNAME=custom_user \
  -e METRICS_PASSWORD=custom_pass \
  -e METRICS_INSTANCE=node-1 \
  -e METRICS_PUSH_URL=https://push.example.com \
  -e METRICS_BASE_PATH=/xray/monitor \
  -e WEB_SHOW_DETAILS=false \
  -e WEB_PUBLIC=false \
  -e LOG_LEVEL=info \
  -e RUN_ONCE=false \
  -p 2112:2112 \
  kutovoys/xray-checker
```

--------------------------------

### Health Check Endpoint

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/api-reference.md

Use this simple GET request to check if the Xray Checker service is running.

```http
GET /health
```

--------------------------------

### Toggle Auto Refresh

Source: https://github.com/kutovoys/xray-checker/blob/main/web/templates/index.html

Manages the auto-refresh functionality, starting or stopping the countdown and saving the preference to local storage.

```javascript
toggleAutoRefresh() {
  this.autoRefresh = !this.autoRefresh;
  localStorage.setItem('autoRefresh', this.autoRefresh);
  this.autoRefresh ? this.startCountdown() : this.stopCountdown();
}
```

--------------------------------

### Get Current IP Address

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Returns the detected public IP address of the checker instance. Requires authentication.

```APIDOC
## GET /api/v1/system/ip

### Description
Returns the detected public IP address of the checker instance.

### Method
GET

### Endpoint
/api/v1/system/ip

### Parameters
#### Query Parameters
- **username** (string) - Required - Basic auth username
- **password** (string) - Required - Basic auth password

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - IP address information.
  - **ip** (string) - The public IP address.

### Response Example
{
  "success": true,
  "data": {
    "ip": "203.0.113.1"
  }
}
```

--------------------------------

### Custom Size Badge URL

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/badges/playground.mdx

Example URL for a badge with custom width and height. Useful for specific dashboard layouts.

```url
https://your-server.com/?stableId=abc123&width=200&height=40
```

--------------------------------

### Configuration Folder Subscription

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/subscription.md

Use the folder:// prefix in SUBSCRIPTION_URL to point to a directory containing multiple V2Ray/Xray JSON configuration files. Files are processed alphabetically.

```bash
SUBSCRIPTION_URL=folder:///path/to/configs
```

--------------------------------

### List All Proxies with Full Information

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/api-reference.md

Retrieves detailed information for all configured proxies. Requires authentication if METRICS_PROTECTED is true.

```http
GET /api/v1/proxies
```

```json
{
  "success": true,
  "data": [
    {
      "index": 0,
      "stableId": "a1b2c3d4e5f67890",
      "name": "US-Server-1",
      "subName": "Premium VPN",
      "server": "192.168.1.1",
      "port": 443,
      "protocol": "vless",
      "proxyPort": 10000,
      "online": true,
      "latencyMs": 150
    }
  ]
}
```

--------------------------------

### Get Current IP Address (Authenticated)

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Returns the public IP address detected by the Xray-Checker instance. Requires authentication.

```bash
# Get current IP
curl -u admin:password http://localhost:2112/api/v1/system/ip
```

```json
# Response
{
  "success": true,
  "data": {
    "ip": "203.0.113.1"
  }
}
```

--------------------------------

### Get Current Checker Configuration

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/api-reference.md

Retrieves the current configuration settings of the Xray Checker. Requires authentication if METRICS_PROTECTED is true.

```http
GET /api/v1/config
```

```json
{
  "success": true,
  "data": {
    "checkInterval": 300,
    "checkMethod": "ip",
    "timeout": 30,
    "startPort": 10000,
    "subscriptionUpdate": true,
    "subscriptionUpdateInterval": 300,
    "simulateLatency": true,
    "subscriptionNames": ["Premium VPN", "Basic VPN"]
  }
}
```

--------------------------------

### Set Instance Label

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/advanced-conf.md

Assign a label to the Xray Checker instance, useful for identifying specific instances in distributed setups.

```bash
METRICS_INSTANCE=datacenter-1
```

--------------------------------

### Configure Download Check Method

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/check-methods.md

Set the proxy check method to 'download' and specify the URL for file download. Configure the timeout for the download and the minimum expected file size.

```bash
--proxy-check-method=download
```

```bash
PROXY_CHECK_METHOD=download
PROXY_DOWNLOAD_URL=https://proof.ovh.net/files/1Mb.dat
PROXY_DOWNLOAD_TIMEOUT=60
PROXY_DOWNLOAD_MIN_SIZE=51200
```

--------------------------------

### Run Xray Checker Binary

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/intro/quick-start.md

Executes the downloaded Xray Checker binary. Ensure you replace 'https://your-subscription-url/sub' with your actual subscription URL.

```bash
./xray-checker --subscription-url=https://your-subscription-url/sub
```

--------------------------------

### Get Single Proxy by Stable ID

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Retrieves detailed information for a specific proxy using its stable identifier. Requires authentication.

```APIDOC
## GET /api/v1/proxies/{stableId}

### Description
Retrieves detailed information for a specific proxy using its stable identifier.

### Method
GET

### Endpoint
/api/v1/proxies/{stableId}

### Parameters
#### Path Parameters
- **stableId** (string) - Required - The stable identifier of the proxy.

#### Query Parameters
- **username** (string) - Required - Basic auth username
- **password** (string) - Required - Basic auth password

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - The proxy object.
  - **index** (integer) - The index of the proxy.
  - **stableId** (string) - The stable identifier for the proxy.
  - **name** (string) - The name of the proxy server.
  - **subName** (string) - The sub-name or type of the proxy.
  - **server** (string) - The server address.
  - **port** (integer) - The server port.
  - **protocol** (string) - The protocol used by the proxy.
  - **proxyPort** (integer) - The proxy port.
  - **online** (boolean) - Indicates if the proxy is currently online.
  - **latencyMs** (integer) - The latency in milliseconds.

#### Error Response (404)
- **success** (boolean) - Indicates if the request was successful.
- **error** (string) - Error message if the proxy is not found.

### Response Example
{
  "success": true,
  "data": {
    "index": 0,
    "stableId": "a1b2c3d4e5f67890",
    "name": "US-Server-1",
    "subName": "Premium VPN",
    "server": "192.168.1.1",
    "port": 443,
    "protocol": "vless",
    "proxyPort": 10000,
    "online": true,
    "latencyMs": 150
  }
}

### Error Response Example
{
  "success": false,
  "error": "Proxy not found"
}
```

--------------------------------

### Get Public Proxies (Unauthenticated)

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Retrieves a list of proxies with their online status and latency, suitable for public display. No authentication is required.

```bash
# Get public proxy list (no auth required)
curl http://localhost:2112/api/v1/public/proxies
```

```json
# Response
{
  "success": true,
  "data": [
    {
      "stableId": "a1b2c3d4e5f67890",
      "name": "US-Server-1",
      "online": true,
      "latencyMs": 150
    },
    {
      "stableId": "b2c3d4e5f6789012",
      "name": "EU-Server-2",
      "online": false,
      "latencyMs": 0
    }
  ]
}
```

--------------------------------

### System Info

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/api-reference.md

Retrieves system version and uptime information.

```APIDOC
## GET /api/v1/system/info

### Description
Returns version and uptime information.

### Method
GET

### Endpoint
/api/v1/system/info

### Response
#### Success Response (200)
- success (boolean) - Indicates if the request was successful.
- data (object) - An object containing system information.
  - version (string) - The version of the Xray Checker.
  - uptime (string) - The uptime of the service in a human-readable format.
  - uptimeSec (integer) - The uptime of the service in seconds.
  - instance (string) - The instance identifier of the service.

### Response Example
```json
{
  "success": true,
  "data": {
    "version": "1.0.0",
    "uptime": "1h 30m 45s",
    "uptimeSec": 5445,
    "instance": "prod-1"
  }
}
```

### Note
This endpoint requires authentication if `METRICS_PROTECTED` is set to `true`.
```

--------------------------------

### Get Specific Proxy by ID

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/api-reference.md

Retrieves detailed information for a single proxy identified by its stableId. Requires authentication if METRICS_PROTECTED is true.

```http
GET /api/v1/proxies/{stableId}
```

--------------------------------

### Uptime Kuma Monitor URL

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/api-reference.md

Example of a monitor URL for Uptime Kuma to check individual proxy status. Authentication can be included if required.

```http
http://localhost:2112/config/a1b2c3d4e5f67890
```

```http
http://username:password@localhost:2112/config/a1b2c3d4e5f67890
```

--------------------------------

### Example: Custom Logo Size CSS

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/web-customization.md

Adjust the size of the logo displayed in the header by targeting the `.header-logo img` selector in your custom CSS.

```css
.header-logo img {
  width: 48px;
  height: 48px;
}
```

--------------------------------

### Get Public Proxy Status

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/api-reference.md

Retrieves proxy status without sensitive data, suitable for web UI auto-refresh. No authentication is required.

```http
GET /api/v1/public/proxies
```

```json
{
  "success": true,
  "data": [
    {
      "stableId": "a1b2c3d4e5f67890",
      "name": "US-Server-1",
      "online": true,
      "latencyMs": 150
    }
  ]
}
```

--------------------------------

### Configure Download Test Method

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Configure the proxy check method to download a minimum amount of data within a specified timeout. Ensure PROXY_DOWNLOAD_MIN_SIZE is set to at least 50KB.

```bash
# Configure download check method
PROXY_CHECK_METHOD=download
PROXY_DOWNLOAD_URL=https://proof.ovh.net/files/1Mb.dat
PROXY_DOWNLOAD_TIMEOUT=60
PROXY_DOWNLOAD_MIN_SIZE=51200  # 50KB minimum
```

--------------------------------

### Basic Prometheus Scraping Configuration

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/integrations/prometheus.md

Use this configuration in your prometheus.yml to scrape metrics from Xray Checker directly. Ensure the job_name matches your setup.

```yaml
scrape_configs:
  - job_name: "xray-checker"
    metrics_path: "/metrics"
    static_configs:
      - targets: ["localhost:2112"]
    scrape_interval: 1m
```

--------------------------------

### Enable Security Authentication

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/advanced-conf.md

Enable and configure basic authentication for sensitive endpoints like metrics. Requires username and password.

```bash
METRICS_PROTECTED=true
METRICS_USERNAME=custom_user
METRICS_PASSWORD=secure_password
```

--------------------------------

### Light Theme Pill Badge URL

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/badges/playground.mdx

Example URL for a badge with a light theme and pill-shaped variant. Customize `stableId`, `theme`, and `variant` as needed.

```url
https://your-server.com/?stableId=abc123&theme=light&variant=pill
```

--------------------------------

### Minimal Status Page Embed Example

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/status-page.md

Use these URL parameters to create a minimal status page embed, hiding the header, footer, and controls.

```url
https://your-server.com/?hideHeader=true&hideFooter=true&hideControls=true
```

--------------------------------

### Set Custom Assets Path

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/web-customization.md

Configure the directory for custom web assets using an environment variable or a CLI flag. Ensure the directory exists for custom assets to load at startup.

```bash
# Environment variable
WEB_CUSTOM_ASSETS_PATH=/path/to/custom
```

```bash
# CLI flag
xray-checker --web-custom-assets-path=/path/to/custom
```

--------------------------------

### V2Ray JSON File Configuration

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/configuration/subscription.md

Use a file path with the file:// prefix in SUBSCRIPTION_URL to load a single V2Ray/Xray JSON configuration file.

```bash
SUBSCRIPTION_URL=file:///path/to/config.json
```

```json
{
  "outbounds": [
    {
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "example.com",
            "port": 443,
            "users": [
              {
                "id": "uuid",
                "encryption": "none"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "tls"
      }
    }
  ]
}
```

--------------------------------

### Get Public Proxies (Unauthenticated)

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Retrieves proxy status without sensitive server information. Suitable for public status pages and does not require authentication.

```APIDOC
## GET /api/v1/public/proxies

### Description
Returns proxy status without sensitive server information - suitable for public status pages.

### Method
GET

### Endpoint
/api/v1/public/proxies

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - An array of public proxy objects.
  - **stableId** (string) - The stable identifier for the proxy.
  - **name** (string) - The name of the proxy server.
  - **online** (boolean) - Indicates if the proxy is currently online.
  - **latencyMs** (integer) - The latency in milliseconds.

### Response Example
{
  "success": true,
  "data": [
    {
      "stableId": "a1b2c3d4e5f67890",
      "name": "US-Server-1",
      "online": true,
      "latencyMs": 150
    }
  ]
}
```

--------------------------------

### Access OpenAPI Documentation

Source: https://context7.com/kutovoys/xray-checker/llms.txt

Access the interactive Swagger UI for API documentation or retrieve the raw OpenAPI specification in YAML format.

```bash
# Interactive API documentation
open http://localhost:2112/api/v1/docs

# Raw OpenAPI specification
curl http://localhost:2112/api/v1/openapi.yaml
```

--------------------------------

### Enable Metrics Authentication

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/cli.md

Configure Xray Checker to protect its metrics endpoint with basic authentication. Requires specifying a username and password.

```bash
./xray-checker \
  --subscription-url=https://your-sub-url \
  --metrics-protected=true \
  --metrics-username=user \
  --metrics-password=pass
```

--------------------------------

### List All Proxies

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/usage/api-reference.md

Retrieves detailed information for all configured proxies.

```APIDOC
## GET /api/v1/proxies

### Description
Returns full information for all proxies.

### Method
GET

### Endpoint
/api/v1/proxies

### Response
#### Success Response (200)
- success (boolean) - Indicates if the request was successful.
- data (array) - An array of proxy objects.
  - index (integer) - The index of the proxy.
  - stableId (string) - The unique identifier for the proxy.
  - name (string) - The name of the proxy.
  - subName (string) - The sub-name of the proxy.
  - server (string) - The server address of the proxy.
  - port (integer) - The port of the proxy.
  - protocol (string) - The protocol used by the proxy.
  - proxyPort (integer) - The proxy port.
  - online (boolean) - The current online status of the proxy.
  - latencyMs (integer) - The latency of the proxy in milliseconds.

### Response Example
```json
{
  "success": true,
  "data": [
    {
      "index": 0,
      "stableId": "a1b2c3d4e5f67890",
      "name": "US-Server-1",
      "subName": "Premium VPN",
      "server": "192.168.1.1",
      "port": 443,
      "protocol": "vless",
      "proxyPort": 10000,
      "online": true,
      "latencyMs": 150
    }
  ]
}
```

### Note
This endpoint requires authentication if `METRICS_PROTECTED` is set to `true`.
```

--------------------------------

### Configure Prometheus Node Exporter

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/integrations/alternatives.md

Add this configuration to your Prometheus setup to scrape metrics from both Xray Checker and node-exporter. Ensure both services are running and accessible.

```yaml
scrape_configs:
  - job_name: "xray-checker"
    static_configs:
      - targets: ["localhost:2112"]
  - job_name: "node"
    static_configs:
      - targets: ["localhost:9100"]
```

--------------------------------

### Clone xray-checker Repository

Source: https://github.com/kutovoys/xray-checker/blob/main/docs/src/content/docs/contributing/guide.md

Clone the repository to your local machine and navigate into the project directory.

```bash
git clone https://github.com/kutovoys/xray-checker.git
cd xray-checker
```