xray-pilot

Self-hosted Xray proxy management for small teams. Push configs over SSH, detect config drift, and generate multi-format subscriptions from one embedded Go binary.

中文文档

Features

• Node lifecycle management for Xray Reality deployments
• Config drift detection with scheduled SHA256 comparisons
• User and group management for subscription access control
• Subscription generation with health-aware node selection
• SSH-based sync with atomic uploads and remote service reloads
• Single-binary deployment with the frontend embedded via go:embed
• Runtime system settings managed from the web UI and persisted in the database

Tech Stack

Layer	Technology
Backend	Go 1.26.1+, Gin, GORM, Zap
Database	SQLite by default, PostgreSQL optional
Auth	JWT bearer tokens, bcrypt
Crypto	AES-GCM for secrets at rest, SHA256 for drift checks
Frontend	React 19, Vite, TypeScript, Tailwind CSS v4

Installation

One-line install

Linux amd64 and arm64 hosts can install the latest release with:

curl -fsSL https://raw.githubusercontent.com/imrui/xray-pilot/main/install.sh | sudo bash

The installer will:

• detect amd64 or arm64
• download the latest GitHub Release
• verify checksums.txt
• install xray-pilot to /usr/local/bin/xray-pilot
• create /etc/xray-pilot/config.yaml
• create and start the xray-pilot.service systemd unit
• generate a random admin password, JWT secret, and crypto master key

Manual install

Platform	Archive
Linux amd64	xray-pilot_<version>_linux_amd64.tar.gz
Linux arm64	xray-pilot_<version>_linux_arm64.tar.gz
macOS amd64	xray-pilot_<version>_darwin_amd64.tar.gz
macOS arm64	xray-pilot_<version>_darwin_arm64.tar.gz

Manual installation steps:

1. Download the matching archive and checksums.txt from the latest GitHub Release.
2. Verify the archive with sha256sum -c checksums.txt --ignore-missing.
3. Extract the binary and place it in your preferred location.
4. Copy config.yaml.example to config.yaml and adjust the values.
5. Start the service with ./xray-pilot.

Quick Start From Source

Prerequisites: Go 1.26.1+, Node.js 24+

git clone https://github.com/imrui/xray-pilot.git
cd xray-pilot

make build

cp config.yaml.example config.yaml
# edit jwt.secret and crypto.master_key before first production run

./xray-pilot

Open http://localhost:2026 and sign in with the administrator account defined in config.yaml.

Configuration

Copy config.yaml.example to config.yaml.

server:
  port: 2026
  mode: release

database:
  driver: sqlite
  dsn: xray-pilot.db

jwt:
  secret: "change-me-use-a-long-random-string"
  expire: 24

crypto:
  master_key: ""

admins:
  - username: admin
    password: "change-me-now"

Runtime settings such as scheduler intervals, SSH defaults, subscription formatting, and Xray log options are stored in the database-backed system settings table and managed from the web UI.

Environment variable override:

XRAY_PILOT_MASTER_KEY=<hex-key> ./xray-pilot

Priority order:

1. XRAY_PILOT_MASTER_KEY
2. config.yaml -> crypto.master_key
3. auto-generated key on first start

Development

# backend
make dev-backend

# frontend
make dev-frontend

The frontend dev server proxies API requests to http://localhost:2026.

Release Automation

Pushing a tag named v* triggers GitHub Actions to:

1. build the frontend with Node 24
2. compile release binaries with Go 1.26
3. package tar.gz archives for Linux and macOS on amd64 and arm64
4. generate checksums.txt
5. publish a GitHub Release with all artifacts attached

License

MIT. See LICENSE.