xrat 🐀

xrat is a command-line proxy configuration manager for Xray-core and sing-box. Import subscriptions, test latency, scan edge IPs, rotate proxies, and run a managed Xray/V2Ray proxy runtime — all from a single Rust binary.

What you can do

• Import proxy configs from subscription URLs, base64 files, or raw VLESS/VMESS/Trojan/Shadowsocks links
• Test proxies with real-delay, TCP ping, ICMP, download/upload speed measurements
• Scan Cloudflare edge IPs and persist working endpoints
• Run Xray-core or V2Ray as a managed runtime with automatic proxy rotation
• Control everything through CLI, terminal UI (TUI), HTTP API, or background daemon

sing-box support currently covers parsing and runtime-config preview, including Hysteria2 diagnostics through xrat parse --engine sing-box. Managed runtime process lifecycle is Xray/V2Ray-focused.

Sections

Getting Started

xrat is a Rust-based CLI tool and daemon for managing proxy configurations. It imports subscription links, parses and normalizes proxy URIs, tests connectivity and performance, previews runtime configs for Xray-core and sing-box, manages an Xray/V2Ray local proxy runtime process, and exposes an HTTP API.

Prerequisites

• Xray-core binary installed and available in PATH
• sing-box binary (optional, used for sing-box parse/preview support)
• Rust toolchain and just when building from source

Installation

Choose one install path:

• Installation Script — recommended Linux install from the latest verified release archive
• Docker Install — run the published container image with bundled Xray-core
• Manual Binary Install — download, verify, and place release files yourself
• Build From Source — Justfile-oriented workflow for local development builds and source installs

Configuration Directory

xrat uses a configuration directory with the following resolution order:

1. --config <path> CLI flag
2. XRAT_PATH environment variable
3. ~/.config/xrat/

The directory layout:

~/.config/xrat/
├── config.toml      # Application configuration
├── db.sqlite        # SQLite database (default)
├── runtime/         # Runtime session files (generated configs, logs)
└── logs/            # Xray/V2Ray process logs

Next Steps

• Quickstart — import, test, and connect in 3 commands
• Installation Script — recommended install path
• Configuration — config.toml reference

Installation Script

Use the installer script for a normal Linux install. It downloads the matching release archive, verifies the checksum, installs xrat, and can run first-time setup for you.

For other install paths, see Docker Install, Manual Binary Install, or Build From Source.

Requirements

Runtime dependencies

Install xray:

bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install

Install sing-box (optional):

curl -fsSL https://sing-box.app/install.sh | sh

System requirements

Install

curl -fsSL https://raw.githubusercontent.com/mhyrzt/xrat/master/install.sh | bash

The installer will:

1. Check for xray and warn if optional sing-box is missing.
2. Detect x86_64 or aarch64.
3. Download the latest GitHub release archive.
4. Verify the archive against SHASUMS256.txt.
5. Install xrat to ~/.local/bin/xrat.
6. Offer to run xrat init.
7. Offer to install and start the systemd user daemon.

To install to a different directory:

INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/mhyrzt/xrat/master/install.sh | bash

Make sure the install directory is in PATH:

export PATH="$HOME/.local/bin:$PATH"

Add that line to ~/.bashrc, ~/.zshrc, or your shell’s equivalent startup file if needed.

Build and Install From Local Checkout

Set BUILD_FROM_SOURCE=1 to have the installer build the binary from the repository instead of downloading a release archive. Run the script directly from the repo root — piping from curl will not work because the script needs Cargo.toml present alongside it.

Requirements: cargo must be in PATH. git, curl, tar, and sha256sum are not needed.

git clone https://github.com/mhyrzt/xrat.git
cd xrat
BUILD_FROM_SOURCE=1 bash install.sh

To install to a different directory:

BUILD_FROM_SOURCE=1 INSTALL_DIR=/usr/local/bin bash install.sh

The script will:

1. Run cargo build --release inside the checkout.
2. Generate man pages and shell completions from the built binary.
3. Install xrat and extras the same way as the release path.
4. Offer first-time setup prompts.

For a pure Cargo-managed install or a development workflow, see Build From Source.

First-Time Setup

If you skipped the installer’s setup prompts, initialize xrat manually:

xrat init

To install the daemon later:

xrat daemon install --start

Then follow the Quickstart to import configs and connect.

State Paths

Docker Install

Use the Docker image when you want xrat and Xray-core in one container. The image is published to GitHub Container Registry on each tagged release.

For host-level systemd daemon management, shell completions, or man pages, use the Installation Script or Manual Binary Install instead.

Pull

docker pull ghcr.io/mhyrzt/xrat:latest

For a specific release, use the version tag:

docker pull ghcr.io/mhyrzt/xrat:0.1.2

State

The container stores all xrat state under /data/xrat.

docker volume create xrat-data

Run commands with the volume mounted:

docker run --rm -it \
  -v xrat-data:/data/xrat \
  ghcr.io/mhyrzt/xrat:latest init

Import and List

docker run --rm -it \
  -v xrat-data:/data/xrat \
  ghcr.io/mhyrzt/xrat:latest import "https://example.com/sub.txt"

docker run --rm -it \
  -v xrat-data:/data/xrat \
  ghcr.io/mhyrzt/xrat:latest list

Serve the HTTP API

Bind the API to all container interfaces and publish the port on the host:

docker run --rm -it \
  -v xrat-data:/data/xrat \
  -p 8080:8080 \
  ghcr.io/mhyrzt/xrat:latest serve --host 0.0.0.0 --port 8080

Run a Local Proxy

The image includes Xray-core. Publish the proxy ports you enable in config.toml.

docker run --rm -it \
  -v xrat-data:/data/xrat \
  -p 1080:1080 \
  ghcr.io/mhyrzt/xrat:latest connect <config-id>

The default generated config binds the SOCKS proxy to 127.0.0.1 inside the container. To reach it from the host through -p, set the runtime host to 0.0.0.0 in /data/xrat/config.toml.

[runtime.socks]
enabled = true
host = "0.0.0.0"
port = 1080

Build Locally

docker build -t xrat .
docker run --rm -it -v xrat-data:/data/xrat xrat --help

Manual Binary Install

Use this path when you want to inspect or place release files yourself instead of running the installer script.

For the recommended path, see Installation Script. To compile from this repository, see Build From Source.

Download

Go to the latest GitHub release and download the archive for your architecture:

Download SHASUMS256.txt from the same release.

Verify

Run the checksum verification from the directory containing the archive and SHASUMS256.txt:

sha256sum -c SHASUMS256.txt --ignore-missing

The command should report OK for the archive you downloaded.

Install Binary

tar -xzf xrat-vX.Y.Z-x86_64-unknown-linux-musl.tar.gz
mkdir -p ~/.local/bin
mv xrat ~/.local/bin/xrat
chmod +x ~/.local/bin/xrat

Ensure ~/.local/bin is in PATH:

export PATH="$HOME/.local/bin:$PATH"

Add that line to your shell startup file if needed.

Install Shell Completions

The release archive includes generated completion files.

Bash

mkdir -p ~/.local/share/bash-completion/completions
cp completions/xrat.bash ~/.local/share/bash-completion/completions/xrat

Reload by opening a new shell or sourcing your Bash startup file.

Zsh

mkdir -p ~/.zfunc
cp completions/_xrat ~/.zfunc/_xrat

Add this to ~/.zshrc if ~/.zfunc is not already in fpath:

fpath=("$HOME/.zfunc" $fpath)
autoload -Uz compinit
compinit

Fish

mkdir -p ~/.config/fish/completions
cp completions/xrat.fish ~/.config/fish/completions/xrat.fish

Install Man Pages

mkdir -p ~/.local/share/man/man1
cp man/man1/*.1 ~/.local/share/man/man1/
mandb ~/.local/share/man

If mandb is unavailable, the man pages are still copied; your system may index them later.

Install Desktop Entry

mkdir -p ~/.local/share/applications
mkdir -p ~/.local/share/icons/hicolor/48x48/apps
mkdir -p ~/.local/share/icons/hicolor/256x256/apps
cp desktop/xrat.desktop ~/.local/share/applications/
cp desktop/icons/xrat-48x48.png ~/.local/share/icons/hicolor/48x48/apps/xrat.png
cp desktop/icons/xrat-256x256.png ~/.local/share/icons/hicolor/256x256/apps/xrat.png
update-desktop-database ~/.local/share/applications/

First-Time Setup

xrat init
xrat daemon install --start

Then follow the Quickstart.

Build From Source

Use this path when you want to build from a checkout, test local changes, or install a development build. The source workflow is Justfile-oriented; direct Cargo commands are shown only where they help explain what each target does.

For release binaries, use Installation Script or Manual Binary Install.

Requirements

Install:

• git
• Rust via rustup
• just
• xray in PATH
• sing-box if you need sing-box parsing or runtime-config preview support

Install just with Cargo if your distribution does not package it:

cargo install just

Check the local task list:

just --list

Clone

git clone https://github.com/mhyrzt/xrat.git
cd xrat

Build

For a development build:

just build

For a release build using the locked dependency graph:

just release

The release binary is written to:

target/release/xrat

Run a local command from the checkout:

just run status

Install From Checkout

Install the current checkout to ~/.cargo/bin/xrat:

just install

Replace an existing Cargo-installed binary:

just reinstall

Remove the Cargo-installed binary:

just uninstall

Ensure ~/.cargo/bin is in PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Rustup usually adds this automatically. Add it to your shell startup file if xrat --version cannot find the installed binary.

Install Man Pages From Source

Generate and install man pages from the local command definitions:

just install-manpages

This writes pages to ~/.local/share/man/man1 and refreshes that man database when mandb is available.

Install Completions From Source

The completions target prints generated completions for the requested shell. Redirect the output to the location your shell reads.

Bash

mkdir -p ~/.local/share/bash-completion/completions
just completions bash > ~/.local/share/bash-completion/completions/xrat

Open a new shell or source your Bash startup file.

Zsh

mkdir -p ~/.zfunc
just completions zsh > ~/.zfunc/_xrat

Add this to ~/.zshrc if needed:

fpath=("$HOME/.zfunc" $fpath)
autoload -Uz compinit
compinit

Fish

mkdir -p ~/.config/fish/completions
just completions fish > ~/.config/fish/completions/xrat.fish

First-Time Setup

Initialize the config directory and database:

xrat init

Install and start the systemd user daemon:

xrat daemon install --start

Then follow the Quickstart.

Source-Tree Checks

Run the same commands as .github/workflows/ci.yml:

just ci

That expands to:

just fmt-rust-check
just lint
just test

For broader local formatting checks across Rust, Markdown, and SQL:

just fmt-check

Useful supporting targets:

Quickstart

This guide walks through the core xrat workflow: import a subscription, test configs, and start a local proxy.

0. Initialize

Run once after installing to create the config directory, default config file, and database:

xrat init

See init for details on what gets created and how to use a custom path via XRAT_PATH.

1. Import a Subscription

Import from a URL:

xrat import https://example.com/subscription

Import from a local file:

xrat import ./subscription.txt

Import raw subscription text directly:

xrat import "vless://uuid@example.com:443?type=ws&security=tls#MyNode"

xrat automatically detects the input format: subscription URL, local file, raw base64-encoded subscription, plain link list, SIP008 JSON, or Xray JSON.

2. List Imported Configs

xrat list configs

Filter by subscription source:

xrat list configs --subscription 1

You can mark a preferred config without starting a proxy:

xrat select 1

Use enable and disable to control whether a config appears in enabled-only workflows:

xrat disable 7
xrat enable 7

3. Test Connectivity

Test a single config by ID:

xrat test 1

Bulk-test all enabled configs:

xrat test --enabled-only --concurrency 4

Skip specific stages:

xrat test 1 --skip-icmp --skip-download

4. Start a Proxy

Start the daemon first:

xrat daemon start

Connect using a tested config:

xrat connect 1

The command sends a daemon IPC request. The daemon starts the Xray (or V2Ray) process with a generated runtime config. By default, it exposes:

• SOCKS5 on 0.0.0.0:1080
• HTTP on 0.0.0.0:8080 (if enabled in config.toml)

5. Check Status

xrat status

6. Disconnect

xrat disconnect

Interactive TUI

For an interactive view over configs, sources, tests, runtime status, and diagnostics:

xrat tui

Using the Daemon

For persistent operation with auto-rotation:

xrat daemon start
xrat proxy start
xrat proxy rotate
xrat proxy status
xrat daemon stop

xrat connect <id> starts one managed runtime session immediately through the daemon. xrat proxy start enables daemon-driven auto-rotation.

See daemon and proxy for details.

Configuration

xrat reads a TOML configuration file from the config directory. The default location is ~/.config/xrat/config.toml.

Override with --config <path> or the XRAT_PATH environment variable.

Sections

Example

[paths]
database = "db.sqlite"
# xray = "/usr/local/bin/xray"
# v2ray = "/usr/local/bin/v2ray"
# sing_box = "/usr/local/bin/sing-box"

[database]
backend = "sqlite"

[database.sqlite]
path = "db.sqlite"

[database.postgres]
user = { env = "XRAT_POSTGRES_USER" }
password = { env = "XRAT_POSTGRES_PASSWORD" }
host = "localhost"
port = 5432
db_name = "xrat"
max_connections = 10
min_connections = 1
connect_timeout_secs = 10

[server]
enabled = false
host = "127.0.0.1"
port = 8080
key = { env = "XRAT_API_KEY" }

[runtime]
engine = "xray"
replace_active_session = true

[runtime.rotation]
enabled = false
interval_secs = 1800
health_trigger_enabled = true
cooldown_secs = 300
test_concurrency = 0
test_stages = ["real_delay", "download"]

[runtime.log]
enabled = true
mask = "none"
dir = "logs"
dns_log = false
level = "warning"
keep = true

[runtime.socks]
enabled = true
host = "0.0.0.0"
port = 1080
udp = true
auth = { enabled = true, username = "xrat", password = { env = "XRAT_SOCKS_PASSWORD" } }

[runtime.http]
enabled = false
host = "0.0.0.0"
port = 8080

[runtime.shadowsocks]
enabled = false
host = "0.0.0.0"
port = 1081
method = "aes-128-gcm"
password = { env = "XRAT_SHADOWSOCKS_PASSWORD" }
network = "tcp,udp"

[runtime.sniffing]
enabled = true
dest_override = ["http", "tls", "quic"]
route_only = true
metadata_only = false
domains_excluded = []
ips_excluded = []

[routing]
domain_strategy = "IPIfNonMatch"

[routing.direct]
domain = []
ip = []
geosite = []
geoip = []

[routing.block]
domain = []
ip = []
geosite = []
geoip = []

[geo]
auto_update = false
update_interval_hours = 168

[[geo.profiles]]
name = "default"
geosite = "https://example.com/geosite.dat"
geoip = "https://example.com/geoip.dat"

[parser]
parse_mode = "strict"

[dns]
query_strategy = "UseSystem"
servers = ["8.8.8.8", "https://1.1.1.1/dns-query"]
use_system_hosts = true
disable_cache = false
disable_fallback = false
enable_parallel_query = true

[dns.hosts]
"domain:example.test" = "127.0.0.1"

[testing]
concurrency = 0
order = ["icmp", "real_delay", "download"]
failure_policy = "continue"

[testing.real_delay]
enabled = true
url = "https://www.gstatic.com/generate_204"
timeout = 10_000

[testing.icmp]
enabled = true
timeout = 3000
attempts = 3

[testing.download]
enabled = false
url = "https://cachefly.cachefly.net/50mb.test"
timeout = 30_000

[testing.tcp]
enabled = true
timeout = 5000

Secret Values

Sensitive fields accept either a literal string or an environment variable reference:

password = "literal-value"
password = { env = "XRAT_SOCKS_PASSWORD" }

Full Reference

See config-file for the complete field reference with all defaults and accepted values.

CLI Reference

xrat is a command-first CLI tool. All operations are invoked as subcommands.

Global Flags

These flags apply to every command:

Commands

Common State Terms

These words appear across the CLI, TUI, API, and database:

Use select to choose a preferred config. Use connect to make a config active by starting a runtime session.

Logging

xrat uses tracing for structured logging. Control verbosity with:

• -v / --verbose: info level
• -vv: debug level
• -vvv: trace level
• -q / --quiet: error level only
• RUST_LOG environment variable: overrides all flags

Logs are written to stderr.

init

Initialize the xrat config directory, config file, and database.

xrat init [--dry-run]

Flags

Behavior

1. Creates the app root directory ($HOME/.config/xrat/ or $XRAT_PATH)
2. Writes a default config.toml with sensible defaults if not already present
3. Creates the SQLite database and runs all pending migrations
4. Creates subdirectories: runtime/, logs/, mmdb/
5. Prints a summary of what was created and what was already present

Idempotent: safe to run multiple times. Existing files are never overwritten. If config.toml exists and has been customized, it is left untouched.

Example: first-time setup

xrat init

xrat initialized successfully.

Created:
  /home/user/.config/xrat/
  /home/user/.config/xrat/config.toml (written default template)
  /home/user/.config/xrat/runtime/
  /home/user/.config/xrat/logs/
  /home/user/.config/xrat/mmdb/

Already present:
  /home/user/.config/xrat/db.sqlite (database ready)

Next steps:
  xrat import <subscription-url>
  xrat list configs

Example: dry run

xrat init --dry-run

--- dry run: no files written ---

Would create (if absent):
  /home/user/.config/xrat/
  /home/user/.config/xrat/config.toml
  /home/user/.config/xrat/db.sqlite
  /home/user/.config/xrat/runtime/
  /home/user/.config/xrat/logs/
  /home/user/.config/xrat/mmdb/

State paths

Default config.toml

The generated config enables SOCKS5 on port 1080, sets the Xray engine, and provides commented-out HTTP inbound and log settings:

[runtime]
engine = "xray"

[runtime.socks]
enabled = true
host = "127.0.0.1"
port = 1080

[runtime.http]
enabled = false
host = "127.0.0.1"
port = 8080

[runtime.log]
enabled = true
level = "warning"

[testing]
concurrency = 4

[geo]
auto_update = false

See Config File for full reference.

Related

• Quickstart
• Configuration
• daemon install — install as a systemd user service

import

Import a subscription URL, file, or raw text into the database.

xrat import <input>

Arguments

Input Formats

xrat automatically detects the input format:

Examples

Import from a subscription URL:

xrat import https://example.com/sub.txt

Import from a local file:

xrat import ./nodes.txt

Import raw base64 subscription text:

xrat import "dmxlc3M6Ly91dWlkQGV4YW1wbGUuY29tOjQ0Mw=="

Import a single share link:

xrat import "vless://uuid@example.com:443?type=ws&security=tls#MyNode"

Behavior

1. Reads input from the specified source
2. Detects format automatically
3. Parses and normalizes each node
4. Deduplicates against existing configs using a versioned key
5. Persists new configs to the database
6. Creates or updates the subscription source record
7. Prints an import summary

Related

• add — add a single config URI without subscription tracking
• list configs — view imported configs

add

Add a single config URI directly to the database.

xrat add <input>

Arguments

Examples

xrat add "vless://uuid-123@example.com:443?type=ws&security=tls&sni=cdn.example.com#Node"

xrat add "ss://YWVzLTI1Ni1nY206c2VjcmV0@example.com:8388#SS%20Node"

Behavior

Unlike import, add does not create a subscription source record. It parses the single URI, normalizes it, deduplicates, and persists directly.

For the full config-management command set, see config management.

Config Management Commands

Manage individual stored configs after import.

These commands operate on config IDs from xrat list configs.

When to Use These Commands

Config State

selected, active, enabled, and deleted are separate states.

Use xrat connect <id> when you want to start a proxy runtime. Use xrat proxy start when you want the daemon to manage automatic rotation.

add

Add a single config URI directly to the database.

xrat add <input>

Arguments

Examples

xrat add "vless://uuid@example.com:443?type=ws&security=tls#Node"

Unlike xrat import, xrat add does not create or update a subscription source record.

show

Show details for one stored config.

xrat show <id> [flags]

Arguments

Flags

Examples

xrat show 42
xrat show 42 --json

select

Select a config as the current selection.

xrat select <id>

Arguments

Selection is useful for workflows that need a preferred config, including the TUI. It does not start or stop the managed runtime.

enable

Enable a config.

xrat enable <id>

Arguments

Enabled configs are included in normal enabled-only workflows, such as:

xrat list configs --enabled-only
xrat test --enabled-only

disable

Disable a config.

xrat disable <id>

Arguments

Disabled configs remain in the database but are excluded from enabled-only queries, tests, and rotation candidate selection.

delete

Soft-delete a config by default.

xrat delete <id> [flags]

Arguments

Flags

Soft-deleted configs are hidden from normal lists but can still be viewed with:

xrat list configs --deleted
xrat list configs --all

Use --hard only when the row should be permanently removed.

restore

Restore a soft-deleted config.

xrat restore <id>

Arguments

restore only applies to soft-deleted configs. It does not recreate a config that was removed with delete --hard.

Related

• list — find config IDs and filter by state
• runtime — connect, disconnect, and inspect active sessions
• tui — manage configs interactively

list

List stored configs or subscription sources.

xrat list <target> [flags]

Targets

list configs

xrat list configs [flags]

Flags

Examples

List all configs:

xrat list configs

List only enabled configs from subscription 3:

xrat list configs --enabled-only --subscription 3

List soft-deleted configs:

xrat list configs --deleted

list subscriptions

xrat list subscriptions [flags]

Flags

Examples

List all subscriptions:

xrat list subscriptions

List only URL-based subscriptions:

xrat list subscriptions --kind url

parse

Parse and validate config links without persisting to the database.

xrat parse [input] [flags]

Arguments

Flags

Engine Modes

This engine choice only affects parse-time validation and --json runtime config preview. Managed runtime commands such as xrat connect use the Xray/V2Ray lifecycle path.

Examples

Parse a single VLESS link:

xrat parse "vless://uuid@example.com:443?type=ws&security=tls&sni=cdn.example.com#Node"

Parse from a file:

xrat parse --file ./links.txt

Parse from stdin:

cat links.txt | xrat parse --stdin

Generate runtime JSON:

xrat parse --json "vless://uuid@example.com:443?type=tcp#Node"

Force sing-box engine:

xrat parse --engine sing-box "hy2://secret@example.com:443?sni=edge.example.com#HY2"

Output

Without --json, prints decoded node fields (protocol, address, port, network, TLS, SNI, etc.).

With --json, prints the full Xray or sing-box runtime configuration JSON that would be generated for the parsed node.

test

Test connectivity and latency for stored configs.

xrat test [id] [flags]

Arguments

Filter Flags

When testing multiple configs (no id specified):

Stage Skip Flags

URL Override Flags

Timeout Override Flags

Concurrency and Output Flags

Ping Loop Flags

Historical Summary Flags

Test Stages

The test command can record up to 5 probe result types:

Stage Order

The default order for ICMP, real-delay, and download is configurable via config.toml:

[testing]
order = ["icmp", "real_delay", "download"]

TCP is used as a gate before real-delay when enabled. Upload runs after download only when --upload-url <url> is provided; there is no [testing.upload] config section.

Failure Policy

Controls behavior when a stage fails:

[testing]
failure_policy = "continue"  # "continue" | "skip_remaining" | "mark_failed"

Examples

Test a single config:

xrat test 42

Bulk-test all enabled configs with 4 workers:

xrat test --enabled-only --concurrency 4

Test with custom URLs and timeouts:

xrat test 1 \
  --test-url https://example.com/generate_204 \
  --download-url https://example.com/10mb.test \
  --real-delay-timeout 5000 \
  --download-timeout 15000

Skip ICMP and download stages:

xrat test 1 --skip-icmp --skip-download

Export results to CSV:

xrat test --enabled-only --format csv --output results.csv

Continuous ping loop:

xrat test 1 --ping --ping-interval 2000

View latest test run summary:

xrat test --latest-run-summary

Filter by country and ASN:

xrat test --latest-run-summary --country US --asn cloudflare

Output Formats

TSV (default)

Tab-separated values, easy to read in terminal:

ID	Protocol	Address	ICMP	TCP	Real Delay	Download	Status
1	vless	example.com:443	15ms	12ms	145ms	-	alive
2	vmess	edge.com:8443	-	-	-	-	timeout

CSV

Comma-separated values, spreadsheet compatible.

JSON

Machine-parseable JSON array with full test result details.

Failure Classification

Test failures are classified into categories:

Related

• list configs — view configs before testing
• connect — start a proxy for a tested config

scan

Scan candidate IPs for TCP reachability and persist results.

xrat scan [flags]

Flags

Examples

Scan specific IPs:

xrat scan --ips 1.1.1.1,8.8.8.8,9.9.9.9

Scan from a file:

xrat scan --file ./candidate-ips.txt

Scan on a custom port with shorter timeout:

xrat scan --ips 1.1.1.1,8.8.8.8 --port 8443 --timeout 2000

View scan history:

xrat scan --history 20

Behavior

1. Reads candidate IPs from --ips or --file
2. Attempts TCP connection to each IP on the specified port
3. Measures connection latency
4. Persists results to the cf_scan_results table (upsert)
5. Prints scan results with latency and success/failure status

Use Cases

• Cloudflare IP scanning: Test candidate Cloudflare edge IPs for low latency
• CDN endpoint testing: Identify fast CDN nodes in your region
• Network reconnaissance: Discover reachable IPs in a range

Output

IP              Port    Latency    Status
1.1.1.1         443     12ms       reachable
8.8.8.8         443     15ms       reachable
9.9.9.9         443     -          timeout

Persistence

Results are persisted to the database and can be retrieved with --history. This allows tracking IP reachability over time and identifying consistently fast endpoints.

Related

• test — test stored proxy configs (not raw IPs)

Runtime Commands

Manage the local proxy runtime through the daemon: connect, disconnect, and check status.

connect

Start a managed proxy runtime for a stored config.

xrat connect <id> [flags]

Arguments

Flags

Examples

xrat connect 42

xrat connect 42 --json

Behavior

1. Sends a runtime-connect request to the daemon over local IPC
2. The daemon loads the config from the database
3. Generates an Xray (or V2Ray) runtime config with local inbounds
4. Spawns the proxy process
5. Waits for the SOCKS port to become ready
6. Persists a runtime_sessions record with status running
7. Prints connection details

If the daemon is not running, start it first:

xrat daemon start

Default Inbounds

Configure inbounds in config.toml under [runtime.socks], [runtime.http], and [runtime.shadowsocks].

Session Replacement

If replace_active_session = true in config.toml, connecting to a new config automatically disconnects the previous session.

Engine Boundary

The managed runtime lifecycle is Xray/V2Ray-focused. xrat parse --engine sing-box can generate sing-box JSON for diagnostics, but connect, disconnect, and status manage the Xray/V2Ray runtime path.

disconnect

Stop the active managed proxy runtime.

xrat disconnect [flags]

Flags

Examples

xrat disconnect

Behavior

1. Sends a runtime-disconnect request to the daemon over local IPC
2. The daemon sends SIGTERM to the running proxy process
3. Waits up to 5 seconds for graceful shutdown
4. Sends SIGKILL if the process is still running
5. Updates the session status to stopped
6. Cleans up temporary config files

status

Show the managed proxy runtime status.

xrat status [flags]

Flags

Examples

xrat status

xrat status --json

Output

Displays:

• Session state: starting, running, stopping, stopped, failed
• Config details: protocol, address, port, name
• Process info: PID, liveness check
• Inbound health: TCP reachability of SOCKS, HTTP, Shadowsocks ports
• Uptime: time since session started

If no daemon is reachable, the command exits with a hint to run xrat daemon start.

JSON Output

{
  "status": "running",
  "session_id": 5,
  "config_id": 42,
  "protocol": "vless",
  "address": "example.com",
  "port": 443,
  "pid": 12345,
  "pid_alive": true,
  "socks_port": 1080,
  "socks_reachable": true,
  "http_port": 8080,
  "http_reachable": false,
  "started_at": "2026-05-28T10:30:00Z"
}

Related

• daemon — persistent daemon with auto-rotation
• proxy — control auto-rotation scheduling
• test — test configs before connecting
• parse — parse and preview Xray or sing-box runtime JSON

daemon

Run or control the daemon supervisor process.

xrat daemon <action>

Actions

The hidden internal run-server action is used by the daemon launcher and is not a user-facing command.

daemon start

Start the long-lived daemon supervisor process.

xrat daemon start

Flags

No command-specific flags.

Behavior

1. Forks a background daemon process
2. Creates a Unix domain socket at <runtime_dir>/daemon.sock
3. Runs the supervisor event loop with:
   • Health checks every 15 seconds
   • IPC event processing from CLI commands
   • Auto-rotation scheduling (if enabled)
4. Reattaches to any stale runtime sessions from previous daemon runs

Daemon Features

• IPC server: Listens for commands from xrat connect, xrat disconnect, etc.
• Health monitoring: Periodically checks proxy liveness, triggers rotation on failure
• Auto-rotation: Scheduled proxy switching with cooldown and candidate testing
• Session reconciliation: Detects and recovers from stale sessions on restart

daemon status

Show daemon IPC reachability and protocol information.

xrat daemon status

Flags

No command-specific flags.

Output

Daemon Status
─────────────────────────────────
Socket:     /home/user/.config/xrat/runtime/daemon.sock
Reachable:  yes
Protocol:   v1

If the daemon is not running or the socket is unreachable, prints an error.

daemon stop

Request daemon shutdown via local IPC.

xrat daemon stop

Flags

No command-specific flags.

Behavior

1. Connects to the daemon socket
2. Sends a shutdown request
3. Daemon gracefully terminates:
   • Stops the active proxy session (if running)
   • Closes the IPC socket
   • Exits cleanly

daemon install

Install xrat as a systemd user service. Linux only.

xrat daemon install [--start] [--with-api] [--dry-run]

Flags

Behavior

1. Resolves the current binary path via std::env::current_exe()
2. Generates xrat-daemon.service from the template in packaging/systemd/ with the resolved binary path and configured XRAT root
3. Writes the service file to ~/.config/systemd/user/ (respects $XDG_CONFIG_HOME)
4. Runs systemctl --user daemon-reload
5. Runs systemctl --user enable xrat-daemon.service
6. If --start: runs systemctl --user start xrat-daemon.service
7. If --with-api: generates and installs xrat-api.service as well

Example

xrat daemon install --start

Written: /home/user/.config/systemd/user/xrat-daemon.service
Reloaded systemd user daemon.
Enabled: xrat-daemon.service
Started: xrat-daemon.service

Daemon installed successfully.

Dry run

xrat daemon install --dry-run

Prints the generated service unit and the systemctl commands that would run, without writing any files or calling systemctl.

daemon uninstall

Remove the installed xrat-daemon.service systemd user service.

xrat daemon uninstall [--dry-run]

Flags

Behavior

1. Stops xrat-daemon.service (non-fatal if not running)
2. Disables xrat-daemon.service
3. Removes ~/.config/systemd/user/xrat-daemon.service
4. Repeats for xrat-api.service if present
5. Runs systemctl --user daemon-reload

User config, database, logs, and all application state are preserved.

IPC Protocol

The daemon uses JSON over Unix domain socket with protocol version 1.

Request Types

Manual proxy rotation uses RuntimeReplace with a manual trigger and optional candidate config ID. There is no separate ProxyRotate IPC request type.

Response Envelope

{
  "protocol_version": 1,
  "ok": true,
  "code": 200,
  "message": "success",
  "payload": { ... }
}

Related

• proxy — control auto-rotation scheduling
• connect — start a proxy via daemon IPC
• status — check proxy status via daemon IPC
• init — initialize config directory before first use
• systemd — full systemd deployment guide

proxy

Control auto-rotating proxy scheduling via the daemon.

xrat proxy <action> [flags]

All proxy actions require a running daemon:

xrat daemon start

Actions

proxy start

Enable automatic proxy rotation on a fixed schedule.

xrat proxy start

Flags

No command-specific flags.

Behavior

1. Sends a request to the daemon via IPC
2. Daemon enables the rotation scheduler with settings from config.toml:

[runtime.rotation]
enabled = true
interval_secs = 1800
health_trigger_enabled = true
cooldown_secs = 300
test_concurrency = 0
test_stages = ["real_delay", "download"]

3. Daemon begins periodic rotation according to the interval

Rotation Triggers

Cooldown

After a rotation, the daemon waits cooldown_secs before allowing another rotation. This prevents rapid switching when multiple triggers fire.

proxy status

Show the current proxy rotation status.

xrat proxy status [flags]

Flags

Output

Proxy Rotation Status
─────────────────────────────────
Enabled:        yes
Interval:       1800s
Last rotation:  2026-05-28 10:30:00 (manual)
Next rotation:  2026-05-28 11:00:00
Cooldown:       300s (inactive)
Active config:  42 (vless://example.com:443)

JSON Output

{
  "enabled": true,
  "interval_secs": 1800,
  "last_trigger": "manual",
  "last_rotation_at": "2026-05-28T10:30:00Z",
  "next_rotation_at": "2026-05-28T11:00:00Z",
  "cooldown_secs": 300,
  "cooldown_active": false,
  "active_config_id": 42
}

proxy rotate

Trigger an immediate manual rotation.

xrat proxy rotate [flags]

Flags

Examples

Rotate to the best candidate automatically:

xrat proxy rotate

Rotate to a specific config:

xrat proxy rotate --config-id 99

Behavior

1. If --config-id is provided, rotates to that specific config
2. Otherwise, selects the best candidate from enabled configs:
   • Tests candidates using test_stages from config.toml
   • Picks the config with the lowest real-delay latency
3. Atomically disconnects the old session and connects the new one
4. Respects cooldown period (rotation is delayed if cooldown is active)

Candidate Selection

When rotating without --config-id:

1. Loads all enabled configs from the database
2. Excludes the currently active config
3. Tests candidates concurrently (up to test_concurrency workers)
4. Filters out configs that fail any test stage
5. Sorts by real-delay latency (lowest first)
6. Selects the top candidate

proxy stop

Disable automatic proxy rotation.

xrat proxy stop

Flags

No command-specific flags.

Behavior

1. Sends a request to the daemon via IPC
2. Daemon disables the rotation scheduler
3. Active proxy session continues running (not disconnected)

Related

• daemon — daemon must be running for proxy commands to work
• connect — start one proxy session through the daemon
• test — test configs before enabling rotation

geoip

Manage GeoLite2 MMDB assets and inspect GeoIP lookup configuration.

xrat geoip <command> [flags]

Subcommands

download

Download one or more GeoLite2 MMDB editions.

xrat geoip download [flags]

If neither --edition nor --all is given, the configured default_editions from [mmdb] are used.

Examples

Download all editions to the default MMDB directory:

xrat geoip download --all

Download a single edition:

xrat geoip download --edition city

Download to a custom directory:

xrat geoip download --all --output ./testdata/xrat/mmdb

update

Refresh all supported GeoLite2 MMDB editions. Equivalent to download --all --force.

xrat geoip update [flags]

Example

xrat geoip update

path

Print the resolved MMDB directory.

xrat geoip path [flags]

Resolution order:

1. --output flag, if provided
2. [mmdb].dir from config (resolved relative to XRAT_PATH or config file location)
3. Default: ~/.config/xrat/mmdb

Examples

xrat geoip path
xrat geoip path --output /custom/path

status

Show MMDB presence and size for each supported edition.

xrat geoip status [flags]

Example

xrat geoip status --strict

lookup

Look up a single IP address through the configured GeoIP backend.

xrat geoip lookup <ip> [flags]

The lookup returns country code, city/region, and ASN information when available.

Examples

xrat geoip lookup 8.8.8.8
xrat geoip lookup 8.8.8.8 --backend ipwhois
xrat geoip lookup 2001:4860:4860::8888 --json

backend

Print the active GeoIP backend configuration.

xrat geoip backend [flags]

Shows the backend type, configured fallback, rate limiting, and cache settings.

Example

xrat geoip backend

Troubleshooting

If geoip status --strict reports missing files, download the supported MMDB editions:

xrat geoip download --all

If MMDB lookup fails but remote lookup works, check the resolved directory:

xrat geoip path
xrat geoip lookup 8.8.8.8 --backend ipwhois

Remote backends can be rate-limited by the provider. Use the default cache unless you specifically need --no-cache for diagnostics.

Related

• [mmdb] config — MMDB asset configuration
• [testing.geoip] config — GeoIP lookup backend configuration
• GeoIP Enrichment — test result enrichment feature

serve

Start the local HTTP API server.

xrat serve [flags]

Flags

Examples

Start with default settings (from config.toml):

xrat serve

Override host and port:

xrat serve --host 0.0.0.0 --port 9090

Configuration

The HTTP API server is configured in config.toml:

[server]
enabled = false
host = "127.0.0.1"
port = 8080
key = { env = "XRAT_API_KEY" }

Operating Modes

Foreground Mode

Run xrat serve to start the API server in the foreground. Useful for development or standalone deployment.

Daemon-Hosted Mode

When enabled = true in config.toml, the daemon automatically starts the HTTP API alongside IPC. The API runs in the same process as the daemon.

systemd Service

Run as a systemd user service:

[Unit]
Description=xrat HTTP API
After=network.target

[Service]
ExecStart=/usr/local/bin/xrat serve
Restart=on-failure
Environment=RUST_LOG=info

[Install]
WantedBy=default.target

API Routes

Query Parameters

/json

/b64

/configs

/configs/{id}

Authentication

If key is set in config.toml, all routes except /health require the key query parameter:

curl "http://localhost:8080/json?key=secret"

curl "http://localhost:8080/configs?key=secret&page=1&per_page=10"

Response Formats

/health

{
  "status": "ok"
}

/json

[
  {
    "id": 42,
    "protocol": "vless",
    "address": "example.com",
    "port": 443,
    "name": "My Node",
    "is_enabled": true,
    "is_active": false,
    "is_selected": false,
    "latest_test": {
      "icmp_ok": true,
      "icmp_ms": 15,
      "tcp_ok": true,
      "tcp_ms": 12,
      "real_delay_ok": true,
      "real_delay_ms": 145,
      "download_mbps": null,
      "tested_at": "2026-05-28T10:00:00Z"
    }
  }
]

/b64

Returns base64-encoded subscription text compatible with v2rayN, Clash, and other clients:

dmxlc3M6Ly91dWlkQGV4YW1wbGUuY29tOjQ0Mz90eXBlPXdzJnNlY3VyaXR5PXRscyNNeSBOb2RlCnZtZXNzOi8v...

/configs

{
  "page": 1,
  "per_page": 20,
  "total": 150,
  "configs": [
    {
      "id": 42,
      "protocol": "vless",
      "address": "example.com",
      "port": 443,
      "name": "My Node",
      "is_enabled": true,
      "is_active": false,
      "is_selected": false,
      "subscription_id": 1,
      "created_at": "2026-05-20T08:00:00Z",
      "updated_at": "2026-05-28T10:00:00Z",
      "latest_test": { ... }
    }
  ]
}

/configs/{id}

{
  "id": 42,
  "protocol": "vless",
  "address": "example.com",
  "port": 443,
  "uuid": "uuid-123",
  "network": "ws",
  "tls": "tls",
  "sni": "cdn.example.com",
  "host": "cdn.example.com",
  "path": "/ray",
  "name": "My Node",
  "is_enabled": true,
  "is_active": false,
  "is_selected": false,
  "subscription_id": 1,
  "created_at": "2026-05-20T08:00:00Z",
  "updated_at": "2026-05-28T10:00:00Z",
  "latest_test": { ... }
}

Use Cases

• Subscription server: Serve configs to mobile/desktop clients via /b64
• Monitoring: Poll /health and /configs for uptime monitoring
• Integration: Build dashboards or automation around /json and /configs
• Proxy management: Query active configs and test results programmatically

Related

• daemon — daemon-hosted API mode
• test — test results are exposed via the API
• list — CLI equivalent of /configs

tui

Start the interactive terminal UI.

xrat tui

The TUI has no command-specific flags. It uses the same global flags as other commands, including --database, --config, --xray, --v2ray, --sing-box, -v, and -q.

The TUI is an interactive view over xrat’s shared database, source, testing, runtime, and diagnostics services. It does not keep a separate copy of business logic: config changes, imports, tests, and runtime operations use the same app services as the CLI commands.

Views

The TUI opens in the Configs view. The bottom bar shows view shortcuts, help and quit actions, active filters, task state, and the latest status message.

Global Keys

Configs View

The Configs view shows stored configs with latest test summaries and config state. The status marker column uses ● for active, ✓ for selected, ✕ for soft-deleted, ○ for disabled, and ! for failed configs. Long names are truncated in the table. It supports focused actions, selected-config bulk actions, test batches, and managed runtime controls.

Search matches the displayed config fields. Sorting can cycle through latency, ID, name, protocol, source, last-tested time, and imported time. Deleted configs are hidden by default; press f to include them.

Soft delete hides a config from normal views and workflows. Purge permanently deletes it. Both destructive actions require confirmation.

The Runtime panel inside the Configs view shows the current managed runtime state, active config, selected config, current task, proxy endpoint, and failure message when present. Runtime actions use the same runtime service as xrat connect, xrat disconnect, and xrat status. The same runtime prerequisites apply: the configured Xray/V2Ray binary must be available, runtime paths must be writable, and daemon/runtime configuration must be valid.

Select a preferred config in the Configs view before starting or switching the runtime. Runtime operations run in the background and reload TUI data after completion.

Sources View

The Sources view lists subscription sources and source metadata. The detail panel also shows the local HTTP API base64 subscription URL when it is available.

The import modal accepts the same input forms as xrat import: subscription URL, file path, raw config link, raw link list, base64 subscription text, SIP008 JSON, or Xray JSON. Press Enter to import and Esc to cancel.

Source refresh and import run as background tasks. When they finish, the TUI reloads database-backed data so the Configs and Sources views reflect the new state.

Tests View

The Tests view shows the latest test run summary, current test settings, progress, and recent results.

The current implementation starts a batch for all enabled, non-deleted configs. It runs TCP and real-delay tests with concurrency 4 and skips download, upload, and ICMP stages. The scope, mode, and concurrency are displayed in the view, but there are not yet keybindings to change them interactively.

While a batch is running, the progress bar updates without blocking navigation. Cancelling requests cooperative cancellation; the active operation reports cancelled once the shared test executor observes the cancellation request.

Diagnostics and Help

Press 4 to open Diagnostics. It summarizes important runtime, database, source, API, and operation state, including recent TUI task messages.

Press ? from any view to open the help modal. Press Esc to close it.

QR and Clipboard Behavior

QR modals are available for focused config URIs, source URLs, and the HTTP API subscription URL. Press Esc or q to close a QR modal.

Clipboard actions use the host clipboard. They can fail in SSH, tmux, Wayland, X11, or headless sessions depending on environment support. When clipboard access fails, the TUI reports the error in the status area.

QR generation can fail if a URI is too long for the QR renderer. When that happens, the QR modal reports the failure instead of crashing.

Related Commands

Troubleshooting

If the TUI cannot start, check that the terminal supports alternate-screen raw mode and run with a higher log level:

xrat -vv tui

If runtime actions fail, verify the equivalent CLI flow first:

xrat daemon start
xrat connect <id>
xrat status

If source/API QR or copy actions report that a URL is unavailable, ensure the source has a stored value and that the HTTP API subscription URL can be built from the current app configuration.

completions

Generate shell completion scripts for xrat.

xrat completions <shell>

This is a hidden command (not shown in --help) intended for shell setup and release packaging.

Arguments

Per-shell installation

Bash

mkdir -p ~/.local/share/bash-completion/completions
xrat completions bash > ~/.local/share/bash-completion/completions/xrat

Reload: open a new shell or source ~/.bashrc.

Zsh

mkdir -p ~/.zfunc
xrat completions zsh > ~/.zfunc/_xrat

Add to ~/.zshrc if not already present:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

Reload: exec zsh.

Fish

xrat completions fish > ~/.config/fish/completions/xrat.fish

Reload: open a new Fish shell.

PowerShell

xrat completions powershell > xrat.ps1
. ./xrat.ps1

Add the dot-source line to your $PROFILE for persistence.

Release packaging

Pre-generated completion scripts are included in release archives under completions/:

CI generates these during the release workflow using xrat completions <shell>.

Related

• Quickstart
• manpage

manpage

Generate roff-format man pages for xrat and all subcommands.

xrat manpage [--output <dir>]

This is a hidden command (not shown in --help) intended for use during release packaging and local installation.

Flags

Behavior

Generates one man page per visible command and subcommand:

• xrat.1 — root command with global flags
• xrat-init.1, xrat-import.1, xrat-daemon.1, … — top-level subcommands
• xrat-daemon-install.1, xrat-daemon-stop.1, … — nested subcommands

Hidden commands (e.g., daemon run-server) are excluded.

Output format is roff/troff compatible with man(1).

Example

xrat manpage --output /tmp/man

/tmp/man/xrat.1
/tmp/man/xrat-init.1
/tmp/man/xrat-import.1
/tmp/man/xrat-daemon.1
/tmp/man/xrat-daemon-install.1
...

Installing locally

mkdir -p ~/.local/share/man/man1
xrat manpage --output ~/.local/share/man/man1
mandb ~/.local/share/man   # update index (may require once)
man xrat
man xrat-daemon-install

Or system-wide:

sudo xrat manpage --output /usr/local/share/man/man1
sudo mandb

Release packaging

CI generates man pages during the release workflow and includes them in release archives under man/:

xrat manpage --output dist/man/man1/

Related

• Quickstart
• init
• daemon

Features

xrat provides a comprehensive set of features for managing proxy configurations and running local proxy services.

Core Features

Feature Highlights

Multi-Protocol Support

xrat supports 7 proxy protocols:

• VLESS — modern, lightweight protocol
• VMess — legacy protocol with encryption
• Shadowsocks — simple SOCKS5-like proxy
• Trojan — TLS-based proxy that mimics HTTPS
• HTTP/HTTPS — standard HTTP proxy
• SOCKS5 — classic SOCKS protocol
• Hysteria2 — QUIC-based protocol (via sing-box)

Dual Database Backend

• SQLite — single-user, file-based, zero configuration
• PostgreSQL — multi-user, connection pooling, production-ready

Engine Support

• Xray-core/V2Ray — managed runtime engines used by xrat connect
• sing-box — parse-time and runtime-config preview support, including Hysteria2 diagnostics through xrat parse --engine sing-box

Configurable Testing Pipeline

• 5 test stages: ICMP, TCP, real-delay, download, upload
• Configurable stage order and failure policy
• Bulk testing with concurrency control
• Failure classification with 10 categories
• GeoIP enrichment for endpoint metadata

Managed Runtime

• Automatic proxy process lifecycle management
• Session state tracking with database persistence
• Graceful shutdown with SIGTERM/SIGKILL fallback
• Stale session recovery on daemon restart

Daemon Supervisor

• Long-lived background process
• Unix domain socket IPC for CLI communication
• Health monitoring with automatic rotation on failure
• Scheduled rotation with cooldown protection

HTTP API

• RESTful endpoints for config access
• Base64 subscription output for mobile clients
• Optional API key authentication
• Paginated config listing with filters

Architecture

See Architecture for details on how these features are implemented.

Importing

xrat imports proxy configurations from multiple sources and formats, automatically detecting the input type and normalizing all configs into a unified internal representation.

Input Sources

Subscription URL

Fetch configs from a remote HTTP endpoint:

xrat import https://example.com/subscription

xrat:

1. Fetches the URL content
2. Parses subscription-userinfo headers for metadata (upload, download, total, expire)
3. Detects format (base64, plain list, JSON)
4. Parses and normalizes each node
5. Persists to database with subscription tracking

Local File

Import from a file on disk:

xrat import ./nodes.txt

Supports the same format detection as URLs.

Raw Text

Import inline subscription text:

xrat import "vless://uuid@example.com:443?type=ws#Node"

Useful for quick imports or scripting.

Input Formats

Single Share Link

A single proxy URI:

vless://uuid-123@example.com:443?type=ws&security=tls&sni=cdn.example.com&path=%2Fray#My%20Node

Supported schemes:

• vless://
• vmess://
• ss://
• trojan://
• http:// / https://
• socks5://
• hysteria2:// / hy2://

Base64 Subscription

Standard v2rayN/Clash subscription format:

dmxlc3M6Ly91dWlkQGV4YW1wbGUuY29tOjQ0Mz90eXBlPXdzJnNlY3VyaXR5PXRscyNNeSBOb2RlCnZtZXNzOi8v...

xrat:

1. Base64-decodes the payload
2. Splits into lines
3. Parses each line as a share link

Plain Link List

Multiple share links, one per line:

vless://uuid-1@example.com:443?type=tcp#Node1
vmess://eyJhZGQiOiJleGFtcGxlLmNvbSIsInBvcnQiOiI0NDMifQ==#Node2
ss://YWVzLTI1Ni1nY206c2VjcmV0@example.com:8388#Node3

Lines starting with # are treated as comments and skipped.

SIP008 JSON

Shadowsocks SIP008 format:

{
  "version": 1,
  "servers": [
    {
      "server": "example.com",
      "server_port": 8388,
      "method": "aes-256-gcm",
      "password": "secret",
      "remarks": "My SS Node"
    }
  ]
}

Xray JSON

Full Xray configuration:

{
  "inbounds": [...],
  "outbounds": [
    {
      "protocol": "vless",
      "settings": {
        "vnext": [...]
      }
    }
  ]
}

xrat extracts outbound configs and converts them to internal nodes.

Format Detection

xrat automatically detects the input format using heuristics:

Normalization

After parsing, xrat normalizes each node:

1. Network defaults: Empty network → tcp
2. WebSocket defaults: Missing host → copy from sni, missing path → /
3. gRPC defaults: Missing path → /
4. TLS cleanup: Empty string tls → None

Deduplication

Before persisting, xrat generates a dedup key for each node and skips duplicates. See Deduplication for details.

Subscription Tracking

Each import creates or updates a subscriptions record:

Configs are linked to their subscription via subscription_id foreign key.

Metadata Extraction

For subscription URLs, xrat extracts metadata from HTTP headers:

subscription-userinfo: upload=1024; download=2048; total=10240; expire=1234567890

Parsed fields:

• upload — bytes uploaded
• download — bytes downloaded
• total — total quota
• expire — expiration timestamp (Unix epoch)

Error Handling

xrat continues parsing even when individual lines fail:

Import Summary
─────────────────────────────────
Source:     https://example.com/sub.txt
Parsed:     45 nodes
Failed:     3 lines
Duplicates: 12 skipped
New:        33 configs added

Failed lines are logged with line numbers and error messages.

Related

• import CLI — command reference
• Deduplication — how duplicates are detected
• Protocols — supported protocol formats

Testing

xrat includes a comprehensive testing pipeline that measures connectivity, latency, and throughput for stored proxy configs.

Test Stages

The test command runs up to 5 stages in sequence:

Stage Configuration

Configure stages in config.toml:

[testing]
concurrency = 0  # 0 = auto-detect
order = ["icmp", "real_delay", "download"]
failure_policy = "continue"

[testing.icmp]
enabled = true
timeout = 3000
attempts = 3

[testing.tcp]
enabled = true
timeout = 5000

[testing.real_delay]
enabled = true
url = "https://www.gstatic.com/generate_204"
timeout = 10_000

[testing.download]
enabled = false
url = "https://cachefly.cachefly.net/50mb.test"
timeout = 30_000

Stage Order

The order array controls ICMP, real-delay, and download ordering. TCP is a gate before real-delay when enabled. Upload is optional and runs after download only when --upload-url is provided.

Example: skip ICMP, run only real-delay and download:

order = ["real_delay", "download"]

Failure Policy

Controls behavior when a stage fails:

ICMP Stage

Measures ICMP ping latency by spawning the system ping command.

Configuration

[testing.icmp]
enabled = true
timeout = 3000   # ms per attempt
attempts = 3     # number of ping packets

Output

• icmp_ok — boolean success
• icmp_ms — average latency in milliseconds
• icmp_attempts — number of packets sent

Implementation

xrat spawns ping -c <attempts> -W <timeout> <address> and parses stdout for packet loss and round-trip times.

TCP Stage

Measures TCP connection latency to the proxy’s address:port.

Configuration

[testing.tcp]
enabled = true
timeout = 5000  # ms

Output

• tcp_ok — boolean success
• tcp_ms — connection time in milliseconds
• failure_kind — failure classification (if failed)

Failure Classification

TCP failures are classified into categories:

Real Delay Stage

Measures actual HTTP round-trip latency through the proxy.

How It Works

1. Generates a temporary Xray probe config with a local SOCKS inbound
2. Spawns a short-lived Xray process
3. Waits for the SOCKS port to become ready
4. Makes an HTTP request through the proxy to the test URL
5. Measures connect time, TTFB, and total round-trip time
6. Terminates the Xray process

Configuration

[testing.real_delay]
enabled = true
url = "https://www.gstatic.com/generate_204"
timeout = 10_000  # ms

Output

• real_delay_ok — boolean success
• real_delay_ms — total round-trip time
• connect_ms — TCP connection time
• ttfb_ms — time to first byte
• http_status — HTTP response status code

Probe Config

The probe config uses a minimal setup:

{
  "log": { "loglevel": "warning" },
  "inbounds": [
    {
      "tag": "probe-in",
      "port": <random>,
      "listen": "127.0.0.1",
      "protocol": "socks",
      "settings": { "udp": false }
    }
  ],
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "<node-protocol>",
      "settings": { ... },
      "stream_settings": { ... }
    }
  ]
}

Download Stage

Measures download throughput by downloading a file through the proxy.

Configuration

[testing.download]
enabled = false
url = "https://cachefly.cachefly.net/50mb.test"
timeout = 30_000  # ms

Output

• download_mbps — throughput in megabits per second

Implementation

1. Spawns proxy with the config
2. Downloads the file through the proxy
3. Measures bytes transferred and elapsed time
4. Calculates throughput: (bytes * 8) / (seconds * 1_000_000)

Upload Stage

Measures upload throughput by POSTing data through the proxy.

Invocation

xrat test 42 --upload-url https://example.com/upload --upload-timeout 30000

Output

• upload_mbps — throughput in megabits per second

Bulk Testing

Test multiple configs concurrently:

xrat test --enabled-only --concurrency 4

Concurrency

• 0 = auto-detect based on CPU cores
• Positive values set exact worker count

Progress Bar

Bulk tests display an animated progress bar (unless --no-progress is used):

Testing configs ━━━━━━━━━━━━━━━━━━━━ 45/150 30% 2m 15s

Output Formats

Sorting

Sort results by:

Ping Loop

Continuous monitoring mode for a single config:

xrat test 42 --ping --ping-interval 2000

Runs the test repeatedly until Ctrl+C, printing a live summary:

Ping loop for config 42 (vless://example.com:443)
─────────────────────────────────────────────────────
#1  ICMP: 15ms  TCP: 12ms  Real Delay: 145ms  ✓
#2  ICMP: 14ms  TCP: 11ms  Real Delay: 142ms  ✓
#3  ICMP: -     TCP: -     Real Delay: -      ✗ timeout
#4  ICMP: 16ms  TCP: 13ms  Real Delay: 148ms  ✓

GeoIP Enrichment

Optionally enrich test results with GeoIP data (country, city, ASN) using configurable lookup backends.

Backend Types

Configuration

[testing.geoip]
enabled = true
backend = "mmdb"             # mmdb | ipwhois | ip-api | chain

mmdb backend

Paths for local GeoLite2 MMDB files. Relative paths are resolved from the config file location, or from XRAT_PATH when set.

[testing.geoip]
country_path = "mmdb/GeoLite2-Country.mmdb"
city_path = "mmdb/GeoLite2-City.mmdb"
asn_path = "mmdb/GeoLite2-ASN.mmdb"

Download MMDB files with the geoip download command.

Remote backends (ipwhois / ip-api)

[testing.geoip.remote]
provider = "ipwhois"         # ipwhois | ip-api
endpoint = ""                # override API endpoint (empty = provider default)
timeout_ms = 5000
api_key = ""                 # provider-specific (if required)
rate_limit_per_minute = 30

Chain backend

Primary is local MMDB; falls back to a remote service on cache/miss or MMDB absence.

[testing.geoip]
backend = "chain"
fallback = "ipwhois"         # ipwhois | ip-api

Caching

Remote lookups are cached in memory to reduce API calls:

[testing.geoip.cache]
enabled = true
ttl_secs = 86400             # per-entry TTL
max_entries = 10000

Test Result Enrichment

When GeoIP enrichment is enabled, test results include:

• endpoint_ip — resolved IP address
• endpoint_country — ISO country code (e.g. NL)
• endpoint_location — location label such as city/country when available
• endpoint_asn — Autonomous System Number and organization (e.g. AS15169 Google LLC)

Related

• geoip CLI — manage MMDB assets, inspect backends, and run ad-hoc IP lookups
• [mmdb] config — MMDB asset configuration
• [testing.geoip] config — full configuration reference

Test Runs

Tests are grouped into runs for historical analysis:

View the latest run summary:

xrat test --latest-run-summary

Filter by country or ASN:

xrat test --latest-run-summary --country US --asn cloudflare

Persistence

All test results are persisted to the database:

Related

• test CLI — command reference
• Runtime Management — uses probe configs for testing
• Database Schema — test result tables

Runtime Management

xrat manages the lifecycle of local proxy processes (Xray or V2Ray), providing automatic config generation, process spawning, health monitoring, and graceful shutdown.

Connect Flow

When you run xrat connect <id>:

1. Load config — Fetch the config from the database by ID
2. Generate runtime config — Create Xray JSON with local inbounds
3. Spawn process — Launch Xray/V2Ray as a child process
4. Wait for readiness — Poll the SOCKS port until it accepts connections
5. Persist session — Insert a runtime_sessions record with status running
6. Return result — Print connection details (ports, PID, config info)

Runtime Config Generation

xrat generates a complete Xray config with:

• Inbounds: SOCKS5, HTTP, Shadowsocks (as configured in config.toml)
• Outbound: Single outbound to the proxy node
• Logging: Configurable log level and file paths
• Stream settings: TLS, WebSocket, gRPC, TCP header obfuscation

Example generated config:

{
  "log": { "loglevel": "warning" },
  "inbounds": [
    {
      "tag": "socks-in",
      "port": 1080,
      "listen": "0.0.0.0",
      "protocol": "socks",
      "settings": { "udp": true }
    },
    {
      "tag": "http-in",
      "port": 8080,
      "listen": "0.0.0.0",
      "protocol": "http"
    }
  ],
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "example.com",
            "port": 443,
            "users": [{ "id": "uuid-123", "encryption": "none" }]
          }
        ]
      },
      "stream_settings": {
        "network": "ws",
        "security": "tls",
        "tls_settings": { "server_name": "cdn.example.com" },
        "ws_settings": {
          "path": "/ray",
          "headers": { "Host": "cdn.example.com" }
        }
      }
    }
  ]
}

Process Spawning

xrat spawns the proxy process with:

• Config file: Written to <runtime_dir>/session-<id>.json
• Stdout: Redirected to <runtime_dir>/session-<id>.out.log
• Stderr: Redirected to <runtime_dir>/session-<id>.err.log
• Detached mode: Process continues running after CLI exits (when using daemon)

Readiness Check

After spawning, xrat polls the SOCKS port every 100ms until:

• Port accepts TCP connections → success
• Process exits → error
• Timeout (default 10s) → error, process is killed

Session State

Each runtime session has a status:

State Transitions

starting → running → stopping → stopped
   ↓                      ↓
 failed                failed

Session Record

Persisted to runtime_sessions table:

Disconnect Flow

When you run xrat disconnect:

1. Load active session — Find the latest running session
2. Send SIGTERM — Request graceful shutdown
3. Wait for exit — Poll process status every 100ms (up to 5s)
4. Send SIGKILL — Force kill if still running after timeout
5. Update session — Set status to stopped or failed
6. Cleanup — Remove temporary config files (if configured)

Graceful Shutdown

xrat attempts graceful shutdown:

#![allow(unused)]
fn main() {
terminate_process_gracefully(pid, Duration::from_secs(5))
}

1. Check if process is running
2. Send SIGTERM
3. Poll every 100ms for up to 5 seconds
4. If still running, send SIGKILL
5. Return outcome: Terminated, Killed, or NotRunning

Status Check

When you run xrat status:

1. Load active session — Find the latest session (any status)
2. Check PID liveness — Verify process is still running
3. Check inbound health — Test TCP reachability of SOCKS/HTTP/Shadowsocks ports
4. Return snapshot — Print status with config details and health

Health Check

For each inbound port:

Session Replacement

When replace_active_session = true in config.toml:

xrat connect 99

If a session is already running:

1. Disconnect the old session (graceful shutdown)
2. Connect the new session
3. Atomic operation from the user’s perspective

This is useful for switching proxies without manual disconnect.

Reattach on Daemon Restart

When the daemon starts, it reconciles stale sessions:

1. Find stale sessions — Query for running sessions with no stopped_at
2. Check PID liveness — For each stale session, check if PID is still running
3. Verify process identity — Compare /proc/<pid>/cmdline with expected binary path
4. Reattach or mark failed:
   • PID alive + cmdline matches → reattach (keep as running)
   • PID alive + cmdline mismatch → mark as failed (different process reused PID)
   • PID dead → mark as failed

Reattach Validation

xrat validates that the PID still belongs to the expected proxy process:

#![allow(unused)]
fn main() {
fn validate_reattach(pid: i64, expected_binary: &Path) -> bool {
    let cmdline = read_proc_cmdline(pid);
    cmdline.contains(expected_binary.to_str().unwrap())
}
}

This prevents reattaching to a different process that happens to have the same PID.

Inbound Configuration

Configure local inbounds in config.toml:

SOCKS5

[runtime.socks]
enabled = true
host = "0.0.0.0"
port = 1080
udp = true
auth = { enabled = true, username = "xrat", password = { env = "XRAT_SOCKS_PASSWORD" } }

HTTP

[runtime.http]
enabled = false
host = "0.0.0.0"
port = 8080

Shadowsocks

[runtime.shadowsocks]
enabled = false
host = "0.0.0.0"
port = 1081
method = "aes-128-gcm"
password = { env = "XRAT_SHADOWSOCKS_PASSWORD" }
network = "tcp,udp"

Sniffing

Enable traffic sniffing for better routing:

[runtime.sniffing]
enabled = true
dest_override = ["http", "tls", "quic"]
route_only = true
metadata_only = false
domains_excluded = []
ips_excluded = []

Logging

Configure proxy process logging:

[runtime.log]
enabled = true
mask = "none"  # "quarter" | "half" | "full" | "none"
dir = "logs"
dns_log = false
level = "warning"  # "debug" | "info" | "warning" | "error"
keep = true

Engine Selection

Choose the proxy engine in config.toml:

[runtime]
engine = "xray"  # "xray" | "v2ray" | "sing-box"

Related

• connect CLI — command reference
• Daemon and IPC — daemon-managed sessions
• Auto-Rotation — automatic proxy switching
• Config Generation — how configs are generated

Daemon and IPC

xrat includes a long-lived daemon supervisor process that manages proxy sessions, monitors health, and handles auto-rotation. CLI commands communicate with the daemon via Unix domain socket IPC.

Daemon Architecture

The daemon runs as a background process with three main responsibilities:

1. IPC Server — Listens for commands from CLI clients
2. Health Monitor — Periodically checks proxy liveness
3. Rotation Scheduler — Manages automatic proxy switching

Supervisor Event Loop

The daemon runs a tokio::select! loop:

#![allow(unused)]
fn main() {
loop {
    tokio::select! {
        _ = health_tick.tick() => {
            check_proxy_health().await;
        }
        Some(event) = ipc_rx.recv() => {
            handle_ipc_event(event).await;
        }
        _ = rotation_timer.tick() => {
            trigger_rotation().await;
        }
    }
}
}

IPC Protocol

The daemon uses JSON over Unix domain socket with protocol version 1.

Socket Location

<runtime_dir>/daemon.sock

Default: ~/.config/xrat/runtime/daemon.sock

Connection Flow

1. CLI command connects to the Unix socket
2. Sends a JSON request
3. Receives a JSON response
4. Closes the connection

Request Format

{
  "protocol_version": 1,
  "request": {
    "type": "RuntimeConnect",
    "payload": {
      "config_id": 42
    }
  }
}

Response Format

{
  "protocol_version": 1,
  "ok": true,
  "code": 200,
  "message": "success",
  "payload": { ... }
}

Request Types

Manual xrat proxy rotate calls RuntimeReplace with trigger = manual and an optional candidate_id. There is no separate ProxyRotate request type.

Response Codes

Daemon Lifecycle

Starting the Daemon

xrat daemon start

1. Check if daemon is already running (try connecting to socket)
2. Fork a background process
3. Create the Unix socket
4. Run the supervisor event loop
5. Reattach to any stale sessions from previous daemon runs

Stopping the Daemon

xrat daemon stop

1. Connect to the daemon socket
2. Send DaemonShutdown request
3. Daemon gracefully terminates:
   • Stops the active proxy session (if running)
   • Closes the IPC socket
   • Exits cleanly

Checking Daemon Status

xrat daemon status

Attempts to connect to the socket and sends a DaemonPing request. Reports whether the daemon is reachable and the protocol version.

Health Monitoring

The daemon periodically checks the health of the active proxy session.

Health Tick Interval

Every 15 seconds, the daemon:

1. Loads the active session from the database
2. Checks if the PID is still running
3. Tests TCP reachability of the SOCKS port
4. If health check fails:
   • Logs the failure
   • Triggers auto-rotation (if health_trigger_enabled)

Health Check Implementation

#![allow(unused)]
fn main() {
async fn check_proxy_health() -> HealthStatus {
    let session = db.get_latest_running_session().await?;

    if !process_is_running(session.process_id) {
        return HealthStatus::ProcessDead;
    }

    if !tcp_connect(session.socks_host, session.socks_port).await {
        return HealthStatus::PortUnreachable;
    }

    HealthStatus::Healthy
}
}

Failure Handling

When a health check fails:

1. Log the failure — Record in daemon logs
2. Update session — Mark as failed with reason
3. Trigger rotation — If health_trigger_enabled, start rotation
4. Respect cooldown — Don’t rotate if cooldown is active

Session Reconciliation

When the daemon starts, it reconciles stale sessions from previous runs.

Stale Session Detection

Query for sessions with:

• status = 'running'
• stopped_at IS NULL

Reconciliation Logic

For each stale session:

1. Check PID liveness — Is the process still running?
2. Verify process identity — Does /proc/<pid>/cmdline match the expected binary?
3. Decision:
   • PID alive + cmdline matches → reattach (keep as running)
   • PID alive + cmdline mismatch → mark failed (different process reused PID)
   • PID dead → mark failed

Reattach Validation

#![allow(unused)]
fn main() {
fn validate_reattach(pid: i64, expected_binary: &Path) -> bool {
    let cmdline_path = format!("/proc/{}/cmdline", pid);
    let cmdline = std::fs::read_to_string(cmdline_path).ok()?;
    cmdline.contains(expected_binary.to_str()?)
}
}

This prevents reattaching to a different process that happens to have the same PID.

IPC Client

CLI commands use an IPC client to communicate with the daemon.

Connection Retry

The client attempts to connect with retry:

#![allow(unused)]
fn main() {
async fn connect_with_retry(socket_path: &Path, max_attempts: u32) -> Result<UnixStream> {
    for attempt in 1..=max_attempts {
        match UnixStream::connect(socket_path).await {
            Ok(stream) => return Ok(stream),
            Err(_) if attempt < max_attempts => {
                sleep(Duration::from_millis(100)).await;
            }
            Err(e) => return Err(e),
        }
    }
}
}

Error Handling

If the daemon is not running or unreachable:

Error: daemon socket not reachable at /home/user/.config/xrat/runtime/daemon.sock
Hint: start the daemon with 'xrat daemon start'

Daemon Integration

CLI Commands via IPC

When the daemon is running, these commands route through IPC:

Daemon Required

Runtime and proxy commands require the daemon IPC path. If the daemon is not running, xrat connect, xrat status, xrat disconnect, and xrat proxy ... return a hint to start it:

xrat daemon start

Supervisor State

The daemon maintains internal state:

#![allow(unused)]
fn main() {
struct SupervisorState {
    rotation_enabled: bool,
    last_rotation_at: Option<DateTime<Utc>>,
    last_trigger: Option<RotationTrigger>,
    cooldown_until: Option<DateTime<Utc>>,
    next_timer_at: Option<DateTime<Utc>>,
    instance_id: String,
}
}

Instance ID

Each daemon instance has a unique ID (UUID v4) used to track session ownership:

#![allow(unused)]
fn main() {
let instance_id = Uuid::new_v4().to_string();
}

Sessions created by the daemon include:

{
  "owner_kind": "daemon",
  "owner_instance_id": "550e8400-e29b-41d4-a716-446655440000"
}

Logging

The daemon logs to stderr and optionally to a file:

xrat daemon start 2> daemon.log

Or with systemd:

[Service]
StandardOutput=journal
StandardError=journal

Log Levels

Control verbosity with RUST_LOG:

RUST_LOG=info xrat daemon start
RUST_LOG=debug xrat daemon start

Security Considerations

Socket Permissions

The Unix socket is created with default permissions (usually 0755). On multi-user systems, consider restricting access:

chmod 700 ~/.config/xrat/runtime/daemon.sock

API Key

The daemon does not enforce authentication for IPC. Security relies on Unix socket permissions and filesystem access control.

For the HTTP API (if enabled), use the key field in config.toml for authentication.

Troubleshooting

Daemon Not Starting

Symptom: xrat daemon start fails or exits immediately

Check:

• Is a daemon already running? xrat daemon status
• Check logs: RUST_LOG=debug xrat daemon start
• Verify socket directory exists and is writable

IPC Connection Failed

Symptom: CLI commands fail with “daemon socket not reachable”

Check:

• Is the daemon running? ps aux | grep xrat
• Does the socket file exist? ls -la ~/.config/xrat/runtime/daemon.sock
• Check socket permissions

Stale Sessions

Symptom: xrat status shows a session but no proxy is running

Fix:

xrat disconnect
xrat daemon stop
xrat daemon start

The daemon will reconcile stale sessions on startup.

Related

• daemon CLI — command reference
• Auto-Rotation — rotation scheduling
• Runtime Management — session lifecycle

Auto-Rotation

xrat supports automatic proxy rotation, periodically switching between configs based on a schedule, health checks, or manual triggers.

Overview

Auto-rotation is managed by the daemon supervisor. When enabled, the daemon:

1. Periodically tests candidate configs
2. Selects the best candidate based on latency
3. Atomically disconnects the old session and connects the new one
4. Respects cooldown periods to prevent rapid switching

Configuration

Enable and configure rotation in config.toml:

[runtime.rotation]
enabled = false
interval_secs = 1800
health_trigger_enabled = true
cooldown_secs = 300
test_concurrency = 0
test_stages = ["real_delay", "download"]

Rotation Triggers

Timer Trigger

Scheduled rotation every interval_secs:

interval_secs = 1800  # rotate every 30 minutes

The daemon maintains a timer that fires at the specified interval, triggering rotation to the best available candidate.

Health Check Trigger

Triggered when the active proxy fails a health check:

health_trigger_enabled = true

The daemon monitors proxy health every 15 seconds. If the health check fails (process dead, port unreachable), rotation is triggered immediately.

Manual Trigger

Triggered by the user via CLI:

xrat proxy rotate

Manual rotation bypasses the timer but respects cooldown.

Forced Rotation

Rotate to a specific config:

xrat proxy rotate --config-id 99

Skips candidate selection and rotates to the specified config.

Cooldown Protection

After a rotation, the daemon enforces a cooldown period:

cooldown_secs = 300  # 5 minutes

During cooldown:

• Timer triggers are delayed until cooldown expires
• Health check triggers are suppressed (unless critical)
• Manual triggers are allowed (user override)

Cooldown State

#![allow(unused)]
fn main() {
struct SupervisorState {
    cooldown_until: Option<DateTime<Utc>>,
    // ...
}
}

When a rotation completes:

#![allow(unused)]
fn main() {
state.cooldown_until = Some(Utc::now() + Duration::from_secs(cooldown_secs));
}

Candidate Selection

When rotating without --config-id, the daemon selects the best candidate:

Step 1: Load Candidates

Query enabled configs from the database:

SELECT * FROM configs
WHERE is_enabled = true
  AND is_deleted = false
  AND id != <current_config_id>

Step 2: Test Candidates

Run test stages on all candidates concurrently:

test_concurrency = 4  # test 4 configs at once
test_stages = ["real_delay", "download"]

For each candidate:

1. Generate a probe config
2. Spawn a short-lived Xray process
3. Run the specified test stages
4. Collect results (latency, throughput, success/failure)
5. Terminate the probe process

Step 3: Filter Failures

Exclude configs that failed any test stage:

#![allow(unused)]
fn main() {
let successful = candidates.into_iter()
    .filter(|c| c.real_delay_ok && c.download_ok)
    .collect();
}

Step 4: Sort by Latency

Sort by real-delay latency (lowest first):

#![allow(unused)]
fn main() {
successful.sort_by_key(|c| c.real_delay_ms);
}

Step 5: Select Top Candidate

Pick the first config from the sorted list:

#![allow(unused)]
fn main() {
let best = successful.first()?;
}

If no candidates pass testing, rotation is skipped.

Rotation Flow

When rotation is triggered:

1. Check cooldown — If active, delay or skip
2. Select candidate — Run candidate selection (or use --config-id)
3. Atomic replace — Disconnect old session, connect new session
4. Update state — Record rotation timestamp, trigger type, new config ID
5. Reset timer — Schedule next timer-based rotation

Atomic Replace

The replace flow ensures minimal downtime:

#![allow(unused)]
fn main() {
async fn replace_session(old_id: i64, new_config_id: i64) -> Result<()> {
    // 1. Start new session
    let new_session = connect(new_config_id).await?;

    // 2. Wait for new session to be ready
    wait_for_ready(new_session.socks_port).await?;

    // 3. Stop old session
    disconnect(old_id).await?;

    Ok(())
}
}

The new session is started before the old session is stopped, ensuring continuous connectivity.

Rotation Status

Check rotation status:

xrat proxy status

Output:

Proxy Rotation Status
─────────────────────────────────
Enabled:        yes
Interval:       1800s
Last rotation:  2026-05-28 10:30:00 (manual)
Next rotation:  2026-05-28 11:00:00
Cooldown:       300s (inactive)
Active config:  42 (vless://example.com:443)

JSON Output

xrat proxy status --json

{
  "enabled": true,
  "interval_secs": 1800,
  "last_trigger": "manual",
  "last_rotation_at": "2026-05-28T10:30:00Z",
  "next_rotation_at": "2026-05-28T11:00:00Z",
  "cooldown_secs": 300,
  "cooldown_active": false,
  "active_config_id": 42
}

Enabling Rotation

Start Rotation

xrat proxy start

Sends a ProxyStart request to the daemon, which enables the rotation scheduler.

Stop Rotation

xrat proxy stop

Sends a ProxyStop request to the daemon, which disables the rotation scheduler. The active proxy session continues running.

Rotation Strategies

Conservative Strategy

Long intervals, strict testing, long cooldown:

[runtime.rotation]
enabled = true
interval_secs = 3600  # 1 hour
health_trigger_enabled = true
cooldown_secs = 600   # 10 minutes
test_stages = ["real_delay", "download"]

Best for: stable connections, minimal disruption

Aggressive Strategy

Short intervals, fast testing, short cooldown:

[runtime.rotation]
enabled = true
interval_secs = 300   # 5 minutes
health_trigger_enabled = true
cooldown_secs = 60    # 1 minute
test_stages = ["real_delay"]

Best for: finding the fastest proxy, frequent optimization

Health-Only Strategy

No scheduled rotation, only rotate on failure:

[runtime.rotation]
enabled = true
interval_secs = 86400  # 24 hours (effectively disabled)
health_trigger_enabled = true
cooldown_secs = 300
test_stages = ["real_delay"]

Best for: stable connections with automatic failover

Persistence

Rotation state is tracked in memory (not persisted to database). On daemon restart:

• Rotation is disabled (must be re-enabled with xrat proxy start)
• Cooldown is reset
• Timer is reset

The active session is persisted and reattached on daemon restart.

Troubleshooting

Rotation Not Triggering

Symptom: Timer fires but rotation doesn’t happen

Check:

• Is cooldown active? xrat proxy status
• Are there enabled configs? xrat list configs --enabled-only
• Do candidates pass testing? xrat test --enabled-only

Rotation Fails

Symptom: Rotation triggers but new session fails to connect

Check:

• Test the target config manually: xrat test <id>
• Check daemon logs for errors
• Verify Xray binary is available

Rapid Rotation

Symptom: Proxy switches too frequently

Fix: Increase cooldown:

cooldown_secs = 600  # 10 minutes

Or disable health trigger:

health_trigger_enabled = false

Related

• proxy CLI — command reference
• Daemon and IPC — daemon supervisor
• Testing — test stages used for candidate selection
• Runtime Management — session lifecycle

IP Scanning

xrat includes a TCP reachability scanner for testing candidate IP addresses, useful for discovering fast CDN endpoints or Cloudflare edge IPs.

Overview

The scan command:

1. Reads candidate IPs from CLI flags or a file
2. Attempts TCP connection to each IP on a specified port
3. Measures connection latency
4. Persists results to the database
5. Prints a summary with reachability and latency

Usage

xrat scan [flags]

Scan Specific IPs

xrat scan --ips 1.1.1.1,8.8.8.8,9.9.9.9

Scan from a File

xrat scan --file ./candidate-ips.txt

File format (one IP per line):

1.1.1.1
8.8.8.8
9.9.9.9
104.16.0.1

Custom Port and Timeout

xrat scan --ips 1.1.1.1,8.8.8.8 --port 8443 --timeout 2000

View History

xrat scan --history 20

Configuration

Scan Process

Step 1: Load IPs

Read IPs from --ips or --file:

#![allow(unused)]
fn main() {
let ips = if !args.ips.is_empty() {
    args.ips.clone()
} else if let Some(file) = &args.file {
    std::fs::read_to_string(file)?
        .lines()
        .map(|s| s.trim().to_string())
        .filter(|s| !s.is_empty())
        .collect()
} else {
    return Err("no IPs provided");
};
}

Step 2: TCP Connect

For each IP, attempt a TCP connection:

#![allow(unused)]
fn main() {
async fn tcp_connect(ip: &str, port: u16, timeout: Duration) -> Result<Duration> {
    let start = Instant::now();
    let addr = format!("{}:{}", ip, port);

    match timeout(timeout, TcpStream::connect(&addr)).await {
        Ok(Ok(_)) => Ok(start.elapsed()),
        Ok(Err(e)) => Err(e.into()),
        Err(_) => Err(Error::Timeout),
    }
}
}

Step 3: Measure Latency

Record the connection time in milliseconds:

#![allow(unused)]
fn main() {
let latency_ms = start.elapsed().as_millis() as u64;
}

Step 4: Persist Results

Insert or update the result in cf_scan_results:

INSERT INTO cf_scan_results (ip, latency_ms, error, last_scanned_at)
VALUES (?, ?, ?, ?)
ON CONFLICT(ip) DO UPDATE SET
  latency_ms = excluded.latency_ms,
  error = excluded.error,
  last_scanned_at = excluded.last_scanned_at

Step 5: Print Summary

IP              Port    Latency    Status
1.1.1.1         443     12ms       reachable
8.8.8.8         443     15ms       reachable
9.9.9.9         443     -          timeout
104.16.0.1      443     8ms        reachable

Persistence

Scan results are persisted to the cf_scan_results table:

Upsert Behavior

Results are upserted (insert or update on conflict):

• New IP → insert new row
• Existing IP → update latency, error, timestamp

This allows tracking IP reachability over time.

History

View persisted scan results:

xrat scan --history 20

Output:

Scan History (latest 20)
─────────────────────────────────────────────────────
IP              Latency    Last Scanned
1.1.1.1         12ms       2026-05-28 10:30:00
8.8.8.8         15ms       2026-05-28 10:30:00
104.16.0.1      8ms        2026-05-28 10:30:00
9.9.9.9         -          2026-05-28 10:30:00 (timeout)

Results are sorted by last_scanned_at descending.

Use Cases

Cloudflare IP Scanning

Discover fast Cloudflare edge IPs:

# Generate candidate IPs from Cloudflare ranges
cat > cf-ips.txt <<EOF
1.1.1.1
1.0.0.1
104.16.0.1
104.17.0.1
EOF

# Scan on port 443
xrat scan --file cf-ips.txt --port 443 --timeout 3000

# View results
xrat scan --history 10

CDN Endpoint Testing

Test CDN nodes in your region:

xrat scan --ips 151.101.1.69,151.101.65.69,151.101.129.69 --port 443

Network Reconnaissance

Discover reachable IPs in a range:

# Generate IP range
for i in {1..254}; do echo "192.168.1.$i"; done > ips.txt

# Scan on custom port
xrat scan --file ips.txt --port 8443 --timeout 1000

Output Format

Success

IP              Port    Latency    Status
1.1.1.1         443     12ms       reachable

Failure

IP              Port    Latency    Status
9.9.9.9         443     -          timeout

Error Types

Performance

Concurrency

Scans are performed sequentially to avoid overwhelming the network. For large IP lists, consider splitting into multiple runs.

Timeout

Adjust timeout based on network conditions:

• Fast network: --timeout 2000 (2 seconds)
• Slow network: --timeout 5000 (5 seconds)
• High latency: --timeout 10000 (10 seconds)

Limitations

• TCP only: Does not support UDP or ICMP
• Single port: Scans one port at a time
• No authentication: Does not test proxy authentication
• Sequential: No parallel scanning (yet)

Related

• scan CLI — command reference
• Testing — test stored proxy configs (not raw IPs)
• Database Schema — cf_scan_results table

HTTP API

xrat includes an Axum-based HTTP API server that exposes stored configs, test results, and subscription-compatible output for integration with external tools and clients.

Overview

The HTTP API provides:

• Health check — verify server is running
• Config listing — query configs with filters and pagination
• Subscription output — base64-encoded subscription text for mobile clients
• JSON export — machine-readable config data with test results

Starting the Server

Foreground Mode

xrat serve

Starts the server in the foreground using settings from config.toml.

Override Host and Port

xrat serve --host 0.0.0.0 --port 9090

Daemon-Hosted Mode

When enabled = true in config.toml, the daemon automatically starts the HTTP API alongside IPC:

[server]
enabled = true
host = "127.0.0.1"
port = 8080

Configuration

[server]
enabled = false
host = "127.0.0.1"
port = 8080
key = { env = "XRAT_API_KEY" }

Routes

Authentication

If key is set in config.toml, all routes except /health require the key query parameter:

curl "http://localhost:8080/json?key=secret"

The key can be a literal string or an environment variable:

key = "literal-secret"
key = { env = "XRAT_API_KEY" }

Route Details

GET /health

Health check endpoint (no authentication required).

Request:

curl http://localhost:8080/health

Response:

{
  "status": "ok"
}

Status: 200 OK

GET /json

List configs with latest test results as a JSON array.

Query Parameters:

Request:

curl "http://localhost:8080/json?key=secret&top=10&enabled=true"

Response:

[
  {
    "id": 42,
    "protocol": "vless",
    "address": "example.com",
    "port": 443,
    "name": "My Node",
    "is_enabled": true,
    "is_active": false,
    "is_selected": false,
    "latest_test": {
      "icmp_ok": true,
      "icmp_ms": 15,
      "tcp_ok": true,
      "tcp_ms": 12,
      "real_delay_ok": true,
      "real_delay_ms": 145,
      "download_mbps": null,
      "tested_at": "2026-05-28T10:00:00Z"
    }
  },
  {
    "id": 43,
    "protocol": "vmess",
    "address": "edge.com",
    "port": 8443,
    "name": "Edge Node",
    "is_enabled": true,
    "is_active": false,
    "is_selected": false,
    "latest_test": {
      "icmp_ok": true,
      "icmp_ms": 18,
      "tcp_ok": true,
      "tcp_ms": 14,
      "real_delay_ok": true,
      "real_delay_ms": 162,
      "download_mbps": null,
      "tested_at": "2026-05-28T10:00:00Z"
    }
  }
]

Status: 200 OK

GET /b64

Base64-encoded subscription text compatible with v2rayN, Clash, and other clients.

Query Parameters:

Request:

curl "http://localhost:8080/b64?key=secret"

Response:

dmxlc3M6Ly91dWlkQGV4YW1wbGUuY29tOjQ0Mz90eXBlPXdzJnNlY3VyaXR5PXRscyNNeSBOb2RlCnZtZXNzOi8v...

Status: 200 OK

Content-Type: text/plain

The response is a base64-encoded string containing one share link per line:

vless://uuid@example.com:443?type=ws&security=tls#My Node
vmess://eyJhZGQiOiJlZGdlLmNvbSIsInBvcnQiOiI4NDQzIn0=#Edge Node

GET /configs

Paginated config list with details.

Query Parameters:

Request:

curl "http://localhost:8080/configs?key=secret&page=1&per_page=10&enabled=true"

Response:

{
  "page": 1,
  "per_page": 10,
  "total": 150,
  "configs": [
    {
      "id": 42,
      "protocol": "vless",
      "address": "example.com",
      "port": 443,
      "uuid": "uuid-123",
      "network": "ws",
      "tls": "tls",
      "sni": "cdn.example.com",
      "host": "cdn.example.com",
      "path": "/ray",
      "name": "My Node",
      "is_enabled": true,
      "is_active": false,
      "is_selected": false,
      "subscription_id": 1,
      "created_at": "2026-05-20T08:00:00Z",
      "updated_at": "2026-05-28T10:00:00Z",
      "latest_test": {
        "icmp_ok": true,
        "icmp_ms": 15,
        "tcp_ok": true,
        "tcp_ms": 12,
        "real_delay_ok": true,
        "real_delay_ms": 145,
        "download_mbps": null,
        "tested_at": "2026-05-28T10:00:00Z"
      }
    }
  ]
}

Status: 200 OK

GET /configs/

Single config detail with latest test results.

Path Parameters:

Query Parameters:

Request:

curl "http://localhost:8080/configs/42?key=secret"

Response:

{
  "id": 42,
  "protocol": "vless",
  "address": "example.com",
  "port": 443,
  "uuid": "uuid-123",
  "password": null,
  "method": null,
  "network": "ws",
  "tls": "tls",
  "sni": "cdn.example.com",
  "host": "cdn.example.com",
  "path": "/ray",
  "name": "My Node",
  "is_enabled": true,
  "is_active": false,
  "is_selected": false,
  "subscription_id": 1,
  "created_at": "2026-05-20T08:00:00Z",
  "updated_at": "2026-05-28T10:00:00Z",
  "latest_test": {
    "icmp_ok": true,
    "icmp_ms": 15,
    "tcp_ok": true,
    "tcp_ms": 12,
    "real_delay_ok": true,
    "real_delay_ms": 145,
    "connect_ms": 10,
    "ttfb_ms": 120,
    "http_status": 204,
    "download_mbps": null,
    "upload_mbps": null,
    "failure_kind": null,
    "failure_reason": null,
    "endpoint_ip": "93.184.216.34",
    "endpoint_country": "US",
    "endpoint_asn": "AS15133",
    "tested_at": "2026-05-28T10:00:00Z"
  }
}

Status: 200 OK

Error Response (config not found):

{
  "error": "config not found",
  "id": 999
}

Status: 404 Not Found

Error Responses

Authentication Failed

{
  "error": "unauthorized"
}

Status: 401 Unauthorized

Not Found

{
  "error": "config not found",
  "id": 999
}

Status: 404 Not Found

Internal Error

{
  "error": "internal server error"
}

Status: 500 Internal Server Error

Use Cases

Subscription Server

Serve configs to mobile/desktop clients:

# v2rayN / Clash
curl "http://localhost:8080/b64?key=secret" > subscription.txt

Configure clients to fetch from http://your-server:8080/b64?key=secret.

Monitoring

Poll health and config status:

# Health check
curl http://localhost:8080/health

# Active configs
curl "http://localhost:8080/configs?key=secret&enabled=true"

Dashboard Integration

Build a web dashboard that queries the API:

fetch("http://localhost:8080/configs?key=secret&page=1&per_page=20")
  .then((r) => r.json())
  .then((data) => {
    console.log(`Total configs: ${data.total}`);
    data.configs.forEach((c) => {
      console.log(`${c.name}: ${c.latest_test?.real_delay_ms}ms`);
    });
  });

Automation

Script proxy management:

# Get top 5 configs by latency
TOP=$(curl -s "http://localhost:8080/json?key=secret&top=5&enabled=true")

# Extract config IDs
IDS=$(echo "$TOP" | jq -r '.[].id')

# Test each config
for id in $IDS; do
  xrat test $id
done

Security Considerations

Bind Address

By default, the server binds to 127.0.0.1 (localhost only). To expose externally:

[server]
host = "0.0.0.0"

Warning: Only expose externally if authentication is enabled and the network is trusted.

API Key

Use a strong, random API key:

# Generate a random key
openssl rand -hex 32

# Set in config.toml
key = "a1b2c3d4e5f6..."

Or use an environment variable:

key = { env = "XRAT_API_KEY" }

export XRAT_API_KEY=$(openssl rand -hex 32)
xrat serve

HTTPS

The server does not support HTTPS natively. Use a reverse proxy (nginx, Caddy) for TLS termination:

server {
    listen 443 ssl;
    server_name xrat.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
    }
}

systemd Service

Run as a systemd user service:

[Unit]
Description=xrat HTTP API
After=network.target

[Service]
ExecStart=/usr/local/bin/xrat serve
Restart=on-failure
Environment=RUST_LOG=info
Environment=XRAT_API_KEY=your-secret-key

[Install]
WantedBy=default.target

Enable and start:

systemctl --user daemon-reload
systemctl --user enable xrat-api
systemctl --user start xrat-api

Related

• serve CLI — command reference
• Daemon and IPC — daemon-hosted API mode
• Deployment — systemd service examples

Deduplication

xrat uses versioned, length-prefixed dedup keys to ensure config uniqueness while distinguishing between None and empty string values.

Overview

When importing configs, xrat:

1. Generates a dedup key for each node
2. Checks if a config with the same key already exists
3. Skips duplicates, only inserting new configs

This prevents the same proxy from being imported multiple times, even across different subscriptions.

Dedup Key Format

The dedup key is a string with the following format:

v1|protocol=<len>:<value>|address=<len>:<value>|port=<len>:<value>|...

Structure

• Version prefix: v1 (allows future format changes)
• Field separator: |
• Field format: <name>=<length>:<value> or <name>=- (for None)

Fields

Length Prefix

Each value is prefixed with its character count:

protocol=5:vless
address=11:example.com
port=3:443

This prevents ambiguity when values contain the separator character (|).

None vs Empty String

• None: Represented as -
• Empty string: Represented as 0:

Example:

username=-          # None
username=0:         # Empty string
username=4:user     # "user"

This distinction is important because some protocols treat None and empty string differently.

Example Keys

VLESS with WebSocket + TLS

v1|protocol=5:vless|address=11:example.com|port=3:443|username=-|uuid=8:uuid-123|password=-|method=-|network=2:ws|tls=3:tls|sni=15:cdn.example.com|host=15:cdn.example.com|path=4:/ray

VMess with TCP

v1|protocol=5:vmess|address=14:vmess.example.com|port=4:8443|username=-|uuid=8:uuid-456|password=-|method=-|network=3:tcp|tls=3:tls|sni=-|host=-|path=-

Shadowsocks

v1|protocol=2:ss|address=11:example.com|port=4:8388|username=-|uuid=-|password=6:secret|method=11:aes-256-gcm|network=3:tcp|tls=-|sni=-|host=-|path=-

Trojan

v1|protocol=6:trojan|address=11:example.com|port=3:443|username=-|uuid=-|password=8:password|method=-|network=3:tcp|tls=3:tls|sni=-|host=-|path=-

Generation

The dedup key is generated from the Node struct:

#![allow(unused)]
fn main() {
impl Node {
    pub fn dedup_key(&self) -> NodeDedupKey {
        NodeDedupKey {
            protocol: self.protocol.clone(),
            address: self.address.clone(),
            port: self.port,
            username: self.username.clone(),
            uuid: self.uuid.clone(),
            password: self.password.clone(),
            method: self.method.clone(),
            network: self.network.clone(),
            tls: self.tls.clone(),
            sni: self.sni.clone(),
            host: self.host.clone(),
            path: self.path.clone(),
        }
    }

    pub fn dedup_key_string(&self) -> String {
        self.dedup_key().to_string()
    }
}
}

Formatting

#![allow(unused)]
fn main() {
impl fmt::Display for NodeDedupKey {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("v1")?;
        write_required(f, "protocol", self.protocol.as_str())?;
        write_required(f, "address", &self.address)?;
        write_required(f, "port", &self.port.to_string())?;
        write_optional(f, "username", self.username.as_deref())?;
        write_optional(f, "uuid", self.uuid.as_deref())?;
        write_optional(f, "password", self.password.as_deref())?;
        write_optional(f, "method", self.method.as_deref())?;
        write_required(f, "network", &self.network)?;
        write_optional(f, "tls", self.tls.as_deref())?;
        write_optional(f, "sni", self.sni.as_deref())?;
        write_optional(f, "host", self.host.as_deref())?;
        write_optional(f, "path", self.path.as_deref())?;
        Ok(())
    }
}

fn write_required(f: &mut fmt::Formatter<'_>, name: &str, value: &str) -> fmt::Result {
    write!(f, "|{}={}:{}", name, value.chars().count(), value)
}

fn write_optional(f: &mut fmt::Formatter<'_>, name: &str, value: Option<&str>) -> fmt::Result {
    match value {
        Some(value) => write_required(f, name, value),
        None => write!(f, "|{}=-", name),
    }
}
}

Database Storage

The dedup key is stored in the configs table:

CREATE TABLE configs (
    id INTEGER PRIMARY KEY,
    subscription_id INTEGER,
    dedup_key TEXT NOT NULL UNIQUE,
    protocol TEXT NOT NULL,
    address TEXT NOT NULL,
    port INTEGER NOT NULL,
    -- ... other fields
);

The UNIQUE constraint on dedup_key enforces uniqueness at the database level.

Import Behavior

When importing configs:

#![allow(unused)]
fn main() {
pub async fn import_nodes(&self, nodes: Vec<Node>, subscription_id: i64) -> Result<ImportSummary> {
    let mut inserted = 0;
    let mut duplicates = 0;

    for node in nodes {
        let dedup_key = node.dedup_key_string();

        match self.insert_config(&node, subscription_id, &dedup_key).await {
            Ok(_) => inserted += 1,
            Err(DbError::UniqueViolation) => duplicates += 1,
            Err(e) => return Err(e),
        }
    }

    Ok(ImportSummary { inserted, duplicates })
}
}

Unique Violation

If a config with the same dedup key already exists, the database returns a unique violation error, which is caught and counted as a duplicate.

Edge Cases

Different Names, Same Config

Two configs with different display names but identical connection parameters are considered duplicates:

vless://uuid@example.com:443?type=ws#Node1
vless://uuid@example.com:443?type=ws#Node2

Both generate the same dedup key (name is not included), so only one is imported.

None vs Empty String

These are treated as different:

#![allow(unused)]
fn main() {
let key1 = NodeDedupKey { password: None, .. };
let key2 = NodeDedupKey { password: Some("".to_string()), .. };

assert_ne!(key1.to_string(), key2.to_string());
}

Key 1: |password=- Key 2: |password=0:

Protocol Differences

Different protocols with the same address/port are not duplicates:

vless://uuid@example.com:443
vmess://uuid@example.com:443

Different protocol field → different dedup keys.

Versioning

The v1 prefix allows future format changes without breaking existing data:

• v1: Current format (length-prefixed)
• v2: Future format (if needed)

When reading dedup keys, xrat checks the version prefix and handles each version appropriately.

Testing

xrat includes tests to verify dedup behavior:

#![allow(unused)]
fn main() {
#[test]
fn distinguishes_none_from_empty_string() {
    let none_key = NodeDedupKey {
        protocol: Protocol::Ss,
        address: "example.com".to_string(),
        port: 8388,
        username: None,
        uuid: None,
        password: None,
        method: None,
        network: "tcp".to_string(),
        tls: None,
        sni: None,
        host: None,
        path: None,
    };
    let empty_key = NodeDedupKey {
        password: Some(String::new()),
        ..none_key.clone()
    };

    assert_ne!(none_key.to_string(), empty_key.to_string());
    assert!(empty_key.to_string().contains("|password=0:"));
}
}

Performance

Dedup key generation is fast:

• String formatting: ~1-2 microseconds per key
• Database lookup: indexed on dedup_key column
• Import performance: ~1000 configs/second (including dedup)

Related

• Importing — how dedup is used during import
• Database Schema — configs table
• Protocols — supported protocols

Deployment

xrat can be deployed in various configurations, from single-user desktop setups to multi-user server deployments with PostgreSQL.

Deployment Options

Quick Deployment Checklist

1. Build xrat: cargo build --release
2. Install binary: Copy target/release/xrat to /usr/local/bin/
3. Create config directory: mkdir -p ~/.config/xrat
4. Write config.toml: Configure database, runtime, testing settings
5. Import subscriptions: xrat import https://example.com/sub.txt
6. Test configs: xrat test --enabled-only
7. Start daemon: xrat daemon start or use systemd
8. Enable rotation (optional): xrat proxy start
9. Start HTTP API (optional): xrat serve or enable in daemon

Environment Variables

xrat respects these environment variables:

Binary Dependencies

xrat requires external proxy binaries:

Ensure binaries are in PATH or specify paths in config.toml:

[paths]
xray = "/usr/local/bin/xray"
v2ray = "/usr/local/bin/v2ray"
sing_box = "/usr/local/bin/sing-box"

Managed runtime process lifecycle is Xray/V2Ray-focused. sing-box is not yet a managed runtime replacement for xrat connect.

Security Considerations

File Permissions

Restrict access to config directory:

chmod 700 ~/.config/xrat
chmod 600 ~/.config/xrat/config.toml
chmod 600 ~/.config/xrat/db.sqlite

Network Exposure

By default, xrat binds to:

• SOCKS5: 0.0.0.0:1080 (all interfaces)
• HTTP API: 127.0.0.1:8080 (localhost only)

To restrict SOCKS5 to localhost:

[runtime.socks]
host = "127.0.0.1"

To expose HTTP API externally (with authentication):

[server]
host = "0.0.0.0"
port = 8080
key = { env = "XRAT_API_KEY" }

Secrets Management

Use environment variables for sensitive values:

[server]
key = { env = "XRAT_API_KEY" }

[runtime.socks]
auth = { enabled = true, username = "xrat", password = { env = "XRAT_SOCKS_PASSWORD" } }

Set in shell profile or systemd service:

export XRAT_API_KEY=$(openssl rand -hex 32)
export XRAT_SOCKS_PASSWORD=$(openssl rand -hex 16)

Monitoring

Health Checks

Use the HTTP API for monitoring:

curl http://localhost:8080/health

Logs

View daemon logs:

journalctl --user -u xrat-daemon -f

Or with direct execution:

RUST_LOG=info xrat daemon start 2> daemon.log

Process Monitoring

Check if daemon is running:

xrat daemon status
ps aux | grep xrat

Backup and Recovery

SQLite

Backup the database file:

cp ~/.config/xrat/db.sqlite ~/backup/db.sqlite.$(date +%Y%m%d)

PostgreSQL

Use pg_dump:

pg_dump xrat > ~/backup/xrat.$(date +%Y%m%d).sql

Config Files

Backup config directory:

tar czf ~/backup/xrat-config.$(date +%Y%m%d).tar.gz ~/.config/xrat/

Troubleshooting

Daemon Won’t Start

Check:

• Is a daemon already running? xrat daemon status
• Check logs: RUST_LOG=debug xrat daemon start
• Verify socket directory is writable

Connection Failed

Check:

• Is Xray binary available? which xray
• Test config manually: xrat test <id>
• Check runtime logs: ~/.config/xrat/runtime/session-*.err.log

Database Locked (SQLite)

Symptom: “database is locked” errors

Fix:

• Only one process can write to SQLite at a time
• Use PostgreSQL for multi-user deployments
• Increase busy timeout in config.toml (if supported)

Related

• systemd — systemd service examples
• Database Backends — SQLite vs PostgreSQL
• Configuration — config.toml reference

systemd Services

Run xrat as a systemd user service for persistent operation and automatic startup on login.

systemd user services run under your user account (not root) and are managed with systemctl --user.

Benefits:

• Auto-start: Service starts on login
• Restart on failure: Automatically restarts if the process crashes
• Logging: Integrated with journalctl

Installation

Use xrat daemon install to generate and enable the service automatically. This is the recommended approach — no manual file editing required.

xrat daemon install

To also start the daemon immediately:

xrat daemon install --start

To install the standalone HTTP API service alongside the daemon:

xrat daemon install --with-api

To preview what would be written without making changes:

xrat daemon install --dry-run

The command:

1. Resolves the current binary path
2. Generates xrat-daemon.service with the correct ExecStart and XRAT_PATH
3. Writes to ~/.config/systemd/user/ (respects $XDG_CONFIG_HOME)
4. Runs systemctl --user daemon-reload
5. Runs systemctl --user enable xrat-daemon.service

Removal

xrat daemon uninstall

Stops, disables, and removes the service file. All user config, database, logs, and application state are preserved.

Preview first:

xrat daemon uninstall --dry-run

Management

systemctl --user start xrat-daemon
systemctl --user stop xrat-daemon
systemctl --user restart xrat-daemon
systemctl --user status xrat-daemon

View logs:

journalctl --user -u xrat-daemon -f
journalctl --user -u xrat-daemon --since today
journalctl --user -u xrat-daemon -n 100

Lingering

By default, user services stop when you log out. To keep the daemon running without an active login session (useful on servers):

loginctl enable-linger $USER

Environment Variables

The generated service file sets XRAT_PATH and RUST_LOG=info. To add secrets (API key, passwords), use an environment file.

Create ~/.config/xrat/env:

XRAT_API_KEY=your-secret-key
XRAT_POSTGRES_PASSWORD=your-db-password

Then add to the service unit after running daemon install:

[Service]
EnvironmentFile=%h/.config/xrat/env

Troubleshooting

Service won’t start:

systemctl --user status xrat-daemon
journalctl --user -u xrat-daemon -n 50

Common causes: binary not found (check ExecStart path), port already in use, config parse error (test with xrat daemon start manually).

Service stops unexpectedly:

journalctl --user -u xrat-daemon --since "1 hour ago"

Logs not appearing: ensure Environment=RUST_LOG=info is set in the unit.

Reference: Manual Setup

If you cannot use xrat daemon install (e.g., the binary is not yet in PATH), you can create the service file manually.

mkdir -p ~/.config/systemd/user

~/.config/systemd/user/xrat-daemon.service:

[Unit]
Description=XRAT Daemon
After=network.target

[Service]
Type=simple
ExecStart=/path/to/xrat daemon run-server
Restart=on-failure
RestartSec=5

Environment=XRAT_PATH=/home/user/.config/xrat
Environment=XRAT_API_KEY=
Environment=RUST_LOG=info

NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/user/.config/xrat
PrivateTmp=true

[Install]
WantedBy=default.target

Replace /path/to/xrat with the actual binary location. Then:

systemctl --user daemon-reload
systemctl --user enable xrat-daemon.service
systemctl --user start xrat-daemon.service

The template files used by xrat daemon install are available in the repository at packaging/systemd/.

Related

• daemon — daemon CLI reference including install/uninstall
• Deployment — deployment overview
• HTTP API — API server details
• Daemon and IPC — daemon supervisor internals

Database Backends

xrat supports both SQLite and PostgreSQL as database backends, allowing flexibility from single-user desktop deployments to multi-user server setups.

Overview

Both backends use the same schema and support all xrat features.

Configuration

Configure the database backend in config.toml:

[database]
backend = "sqlite"  # "sqlite" | "postgres"

[database.sqlite]
path = "db.sqlite"

[database.postgres]
user = { env = "XRAT_POSTGRES_USER" }
password = { env = "XRAT_POSTGRES_PASSWORD" }
host = "localhost"
port = 5432
db_name = "xrat"
max_connections = 10
min_connections = 1
connect_timeout_secs = 10

SQLite

SQLite is the default backend, ideal for single-user deployments.

Advantages

• Zero configuration: No server setup required
• Single file: Database is a single file on disk
• Portable: Easy to backup and move
• Fast: Excellent read performance

Limitations

• Single writer: Only one process can write at a time
• No concurrent access: Not suitable for multi-user deployments
• File locking: “database is locked” errors under high concurrency

Configuration

[database]
backend = "sqlite"

[database.sqlite]
path = "db.sqlite"  # relative to config directory or absolute

File Location

The database file is resolved in this order:

1. --database <path> CLI flag
2. [database.sqlite].path in config.toml
3. [paths].database in config.toml (deprecated)
4. XRAT_PATH/db.sqlite
5. ~/.config/xrat/db.sqlite

Backup

Backup the database file:

cp ~/.config/xrat/db.sqlite ~/backup/db.sqlite.$(date +%Y%m%d)

Performance Tuning

For better write performance, consider:

• WAL mode: Enabled by default in xrat
• Busy timeout: Configured internally (5 seconds)
• Indexing: Automatic on frequently queried columns

Troubleshooting

“database is locked” errors:

• Only one process can write to SQLite at a time
• Ensure no other xrat processes are running
• Consider PostgreSQL for multi-user deployments

PostgreSQL

PostgreSQL is recommended for multi-user deployments and high concurrency.

Advantages

• Concurrent access: Multiple readers and writers
• Connection pooling: Efficient connection management
• Scalability: Handles large datasets and high traffic
• Reliability: ACID compliance, crash recovery

Limitations

• Server required: Must install and configure PostgreSQL
• Network overhead: Slightly slower than SQLite for single-user
• Complexity: More setup and maintenance

Installation

Install PostgreSQL:

Ubuntu/Debian:

sudo apt install postgresql postgresql-contrib

macOS:

brew install postgresql

Docker:

docker run -d \
  --name xrat-postgres \
  -e POSTGRES_USER=xrat \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=xrat \
  -p 5432:5432 \
  postgres:15

Setup

1. Create database and user:

sudo -u postgres psql

CREATE USER xrat WITH PASSWORD 'your-password';
CREATE DATABASE xrat OWNER xrat;
GRANT ALL PRIVILEGES ON DATABASE xrat TO xrat;
\q

2. Configure xrat:

[database]
backend = "postgres"

[database.postgres]
user = "xrat"
password = "your-password"
host = "localhost"
port = 5432
db_name = "xrat"
max_connections = 10
min_connections = 1
connect_timeout_secs = 10

3. Use environment variables (recommended):

[database.postgres]
user = { env = "XRAT_POSTGRES_USER" }
password = { env = "XRAT_POSTGRES_PASSWORD" }
host = "localhost"
port = 5432
db_name = "xrat"

export XRAT_POSTGRES_USER=xrat
export XRAT_POSTGRES_PASSWORD=your-password
xrat import https://example.com/sub.txt

Connection Pooling

xrat uses a connection pool for PostgreSQL:

Tune based on your workload:

• Low traffic: max_connections = 5
• Medium traffic: max_connections = 10
• High traffic: max_connections = 20-50

Backup

Use pg_dump for backups:

# Full backup
pg_dump xrat > ~/backup/xrat.$(date +%Y%m%d).sql

# Compressed backup
pg_dump -Fc xrat > ~/backup/xrat.$(date +%Y%m%d).dump

# Restore
pg_restore -d xrat ~/backup/xrat.20260528.dump

Performance Tuning

PostgreSQL configuration (postgresql.conf):

# Memory
shared_buffers = 256MB
effective_cache_size = 1GB
work_mem = 16MB

# WAL
wal_level = replica
max_wal_size = 2GB

# Connections
max_connections = 100

Indexing: xrat automatically creates indexes on:

• configs.dedup_key (unique)
• configs.subscription_id
• connection_tests.config_id
• connection_tests.run_id
• runtime_sessions.config_id

High Availability

For production deployments, consider:

• Replication: Streaming replication for read replicas
• Connection pooling: PgBouncer or Pgpool-II
• Monitoring: pg_stat_statements, Prometheus exporter
• Backups: Automated daily backups with WAL archiving

Schema Migrations

xrat uses SQLx for schema migrations. Migrations run automatically on startup:

#![allow(unused)]
fn main() {
sqlx::migrate!("./migrations/sqlite").run(&pool).await?;
}

Migration Files

Located in migrations/sqlite/ and migrations/postgres/:

0001_init.sql
0002_add_connection_test_download_mbps.sql
0003_canonical_config_dedup_key.sql
...
0015_add_config_soft_delete.sql

Manual Migration

If migrations fail, run manually:

# SQLite
sqlite3 ~/.config/xrat/db.sqlite < migrations/sqlite/0001_init.sql

# PostgreSQL
psql xrat < migrations/postgres/0001_init.sql

Switching Backends

To switch from SQLite to PostgreSQL:

1. Export data from SQLite:

sqlite3 ~/.config/xrat/db.sqlite .dump > xrat-data.sql

2. Convert SQL (SQLite → PostgreSQL syntax):

# Manual conversion or use tools like pgloader
pgloader sqlite:///path/to/db.sqlite postgresql://xrat:password@localhost/xrat

3. Update config.toml:

[database]
backend = "postgres"

4. Import data:

psql xrat < xrat-data-converted.sql

Monitoring

SQLite

Check database size:

ls -lh ~/.config/xrat/db.sqlite

Check integrity:

sqlite3 ~/.config/xrat/db.sqlite "PRAGMA integrity_check;"

PostgreSQL

Check connection count:

SELECT count(*) FROM pg_stat_activity WHERE datname = 'xrat';

Check table sizes:

SELECT
    schemaname,
    tablename,
    pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

Check slow queries:

SELECT query, calls, total_time, mean_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

Security

SQLite

• File permissions: Restrict access to database file

chmod 600 ~/.config/xrat/db.sqlite

PostgreSQL

• Authentication: Use strong passwords
• SSL: Enable SSL for remote connections
• Firewall: Restrict access to PostgreSQL port (5432)
• User permissions: Use dedicated user with minimal privileges

-- Read-only user for monitoring
CREATE USER xrat_read WITH PASSWORD 'read-password';
GRANT SELECT ON ALL TABLES IN SCHEMA public TO xrat_read;

Related

• Deployment — deployment overview
• Database Schema — table definitions
• Configuration — config.toml reference

Reference

This section provides lookup material for xrat’s configuration, protocols, database schema, and error codes.

Pages

Protocols

xrat supports 7 proxy protocols, each with specific URI formats, configuration fields, and engine routing.

Supported Protocols

VLESS

Modern, lightweight protocol from the Xray project.

Scheme: vless://

Format:

vless://<uuid>@<address>:<port>?type=<network>&security=<tls>&sni=<sni>&host=<host>&path=<path>#<name>

Fields:

Examples:

vless://uuid-123@example.com:443?type=ws&security=tls&sni=cdn.example.com&path=%2Fray#My%20Node
vless://uuid-456@example.com:443?type=tcp#Direct
vless://uuid-789@example.com:8443?type=grpc&serviceName=service#gRPC%20Node

Engine: Xray (auto), Xray (explicit)

VMess

Legacy protocol with encryption, from V2Ray.

Scheme: vmess://

Format:

vmess://<base64-json>

Base64 JSON Fields:

{
  "add": "example.com",
  "port": "443",
  "id": "uuid-456",
  "net": "ws",
  "tls": "tls",
  "sni": "edge.example.com",
  "host": "host.example.com",
  "path": "/vmess",
  "ps": "VMess Node"
}

Example:

vmess://eyJhZGQiOiJleGFtcGxlLmNvbSIsInBvcnQiOiI0NDMiLCJpZCI6InV1aWQtNDU2IiwibmV0Ijoid3MiLCJ0bHMiOiJ0bHMiLCJzbmkiOiJlZGdlLmV4YW1wbGUuY29tIiwiaG9zdCI6Imhvc3QuZXhhbXBsZS5jb20iLCJwYXRoIjoiL3ZtZXNzIiwicHMiOiJWTWVzcyBOb2RlIn0=

Engine: Xray (auto), Xray (explicit)

Shadowsocks

Simple, secure proxy protocol.

Scheme: ss://

Format:

ss://<base64(method:password)>@<address>:<port>#<name>

Fields:

Encryption methods: aes-128-gcm, aes-256-gcm, chacha20-ietf-poly1305, xchacha20-ietf-poly1305, aes-128-cfb, aes-256-cfb, rc4-md5

Example:

ss://YWVzLTI1Ni1nY206c2VjcmV0@example.com:8388#SS%20Node

Engine: Xray (auto), Xray (explicit)

Trojan

TLS-based proxy that mimics HTTPS traffic.

Scheme: trojan://

Format:

trojan://<password>@<address>:<port>?type=<network>&sni=<sni>&host=<host>&path=<path>#<name>

Fields:

Default TLS: Trojan always uses TLS (security=tls is added automatically).

Examples:

trojan://password@example.com:443?type=ws&sni=cdn.example.com&path=%2Ftrojan#Trojan%20Node

Engine: Xray (auto), Xray (explicit)

HTTP

Standard HTTP/HTTPS proxy.

Scheme: http:// / https://

Format:

http://<username>:<password>@<address>:<port>#<name>
https://<username>:<password>@<address>:<port>#<name>

Fields:

TLS: https:// scheme automatically sets tls=tls.

Examples:

http://user:pass@example.com:8080#HTTP%20Node
https://example.com:443#HTTPS%20Node

Engine: Xray (auto), Xray (explicit)

SOCKS5

Standard SOCKS5 proxy.

Scheme: socks5://

Format:

socks5://<username>:<password>@<address>:<port>#<name>

Fields:

Examples:

socks5://user:pass@example.com:1080#SOCKS%20Node
socks5://example.com:1080#Anonymous

Engine: Xray (auto), Xray (explicit)

Hysteria2

QUIC-based protocol designed for high-speed connections.

Scheme: hysteria2:// / hy2://

Format:

hysteria2://<password>@<address>:<port>?sni=<sni>&obfs=<type>&obfs-password=<pass>#<name>
hy2://<password>@<address>:<port>?sni=<sni>&obfs=<type>&obfs-password=<pass>#<name>

Fields: