xrat - Xray-core and sing-box proxy manager

xrat is an open-source Rust CLI and TUI proxy configuration manager for XTLS/Xray-core, V2Ray-core, and SagerNet/sing-box. Import proxy subscriptions, test latency, scan Cloudflare/CDN edge IPs, rotate proxies, and run managed local proxy sessions from a single terminal application.

xrat is built for VLESS, VMess, Trojan, Shadowsocks, SOCKS5, HTTP, and Hysteria2 workflows. It can preview Xray and sing-box JSON, expose local SOCKS/HTTP/Shadowsocks inbounds, supervise runtime sessions with a daemon, and serve stored configs through an authenticated HTTP API.

What you can do

• Import subscriptions, files, raw links, base64 lists, SIP008 JSON, and Xray JSON into SQLite or PostgreSQL.
• Support VLESS, VMess, Trojan, Shadowsocks, HTTP, SOCKS5, and Hysteria2 parsing/preview.
• Deduplicate configs with normalized, versioned keys while preserving subscription metadata.
• Test proxies with ICMP, TCP, real-delay, download, and upload stages.
• Rank bulk test results with concurrency control, failure classification, history, and GeoIP enrichment.
• Run Xray-core, V2Ray-core, or sing-box-backed Hysteria2 as a managed local proxy runtime.
• Expose SOCKS5, HTTP, and Shadowsocks inbounds with configurable ports and sniffing.
• Supervise runtime sessions through a daemon with IPC, health checks, and stale-session reattach.
• Rotate proxies automatically on schedule or health failure, with cooldown and manual override.
• Scan Cloudflare/CDN edge IPs and persist reachable endpoints with latency.
• Control configs through CLI, interactive TUI, HTTP API, or systemd user services.
• Serve stored configs as JSON or base64 subscriptions with optional API-key authentication.
• Manage config state with enable, disable, soft delete, restore, purge, and detailed show commands.
• Inspect operational events with xrat logs for daemon, runtime, rotation, health, and test activity.
• Generate shell completions, man pages, Docker images, and self-upgrade from releases or source.

SagerNet/sing-box support covers sing-box JSON preview and managed Hysteria2 runtime sessions. Hy2 configs automatically launch through sing-box because Xray/V2Ray cannot express that protocol; other managed runtime protocols still use Xray/V2Ray unless [runtime].engine selects a supported engine.

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 plus sing-box-backed Hysteria2 sessions, and exposes an HTTP API.

Prerequisites

• Xray-core binary installed and available in PATH
• Proxy cores: Xray is required for runtime use; setup can install Xray, sing-box, and V2Ray as verified user-local tools
• 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
• Cargo Install — cargo install xrat from crates.io
• 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 or macOS 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

xrat setup detects these tools, checks their latest stable versions, and can install verified user-local copies without root access. Managed files live under ~/.local/share/xrat/cores, with commands linked into ~/.local/bin. Existing system or package-manager installations are never overwritten.

The upstream system installers remain available when a system-wide service is preferred. Install Xray system-wide:

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

Install sing-box if you need Hysteria2 (hy2) managed runtime support:

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

Install V2Ray system-wide on a supported systemd Linux distribution:

bash -c "$(curl -L https://raw.githubusercontent.com/v2fly/fhs-install-v2ray/master/install-release.sh)"

System requirements

Platform Support

Core CLI, config import, parsing, testing, and the TUI work on any Unix-like platform xrat compiles for. Platform integrations vary:

macOS and BSD integrations are newer; the FreeBSD/OpenBSD rows are expected to work but are not yet verified on hardware. Windows is tracked separately and not yet supported.

Install

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

To run all setup prompts with yes answers:

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

The installer will:

1. Detect the OS and architecture and pick the release target triple.
2. Download the latest GitHub release archive.
3. Verify the archive against SHASUMS256.txt (sha256sum or shasum).
4. Install xrat to ~/.local/bin/xrat.
5. Hand off to xrat setup for post-install setup: managed dependency checks and optional installs, xrat init, the background daemon, shell completions, man pages, an xratui shortcut, and (Linux/XDG) the desktop launcher and icons.

Setup runs in the binary, so it works the same regardless of how xrat was installed and can be re-run any time with xrat setup. See the setup reference for the full step list and --check diagnostics.

Useful flags (passed through to xrat setup):

To install to a different directory:

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

To skip the desktop launcher:

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

The desktop launcher starts the TUI in a detected terminal emulator. When the installer finds a supported terminal, it generates a launcher that sets xrat’s window identity for taskbar/dock icon matching on X11 or Wayland. If no supported terminal is found, the launcher falls back to the desktop’s default terminal behavior and the taskbar icon may belong to that terminal window.

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

Pass --from-source 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
bash install.sh --from-source

To install to a different directory:

bash install.sh --from-source --install-dir /usr/local/bin

To skip prompts:

bash install.sh --from-source --yes

The script will:

1. Run cargo build --release inside the checkout.
2. Install xrat to the install directory.
3. Hand off to xrat setup, which generates man pages, completions, and desktop assets from the built binary the same way as the release path.

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

First-Time Setup

If you installed xrat another way (e.g. cargo install, a package manager, or a manual copy), or skipped the installer’s setup, run setup yourself:

xrat setup

This is idempotent and re-runnable, so it also works to finish or repair an install. Check what is and isn’t configured without changing anything:

xrat setup --check

To do just the individual pieces instead: xrat init for the config directory and database, or xrat daemon install --start for the background daemon.

Then follow the Quickstart to import configs and connect.

State Paths

Docker Install

Use the Docker image when you want xrat, Xray-core, and sing-box 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

Define a reusable alias so setup and read-only xrat commands run with the volume mounted:

alias xrat-docker='docker run --rm -it -v xrat-data:/data/xrat ${XRAT_DOCKER_OPTS:-} ghcr.io/mhyrzt/xrat:latest'

Add it to your shell profile if you want it available in new terminals. Then initialize the data directory:

xrat-docker init

Import and List

xrat-docker import "https://example.com/sub.txt"

xrat-docker list

Serve the HTTP API

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

XRAT_DOCKER_OPTS="-p 18203:18203"
xrat-docker serve --host 0.0.0.0

Then verify it from the host:

curl http://localhost:18203/health

Run a Local Proxy

xrat connect talks to the local daemon IPC socket, so the proxy container must keep the daemon running while you connect from another command. Publish the proxy ports you enable in config.toml; the generated defaults use SOCKS on 18200, HTTP on 18201, Shadowsocks on 18202, and the API server on 18203.

docker run -d --name xrat \
  -v xrat-data:/data/xrat \
  -p 127.0.0.1:18200:18200 \
  ghcr.io/mhyrzt/xrat:latest daemon run-server

docker exec -it xrat xrat connect <config-id>

The generated config already binds the SOCKS proxy to 0.0.0.0 inside the container. Keep the Docker publish address restricted to 127.0.0.1 unless you intentionally want LAN access.

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

If you also enable the HTTP proxy, Shadowsocks inbound, or API server in config.toml, publish their matching container ports:

-p 127.0.0.1:18201:18201  # HTTP proxy
-p 127.0.0.1:18202:18202  # Shadowsocks inbound
-p 127.0.0.1:18203:18203  # HTTP API, requires [server].host = "0.0.0.0"

Stop the long-running container when finished:

docker stop xrat
docker rm xrat

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 platform:

Download SHASUMS256.txt from the same release.

Verify

Run the checksum verification from the directory containing the archive and SHASUMS256.txt. On Linux use sha256sum; on macOS use shasum -a 256:

sha256sum -c SHASUMS256.txt --ignore-missing   # Linux
shasum -a 256 -c SHASUMS256.txt --ignore-missing  # macOS

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.

Run Setup

The release archive ships only the binary; man pages, shell completions, and the desktop launcher are generated from the binary itself. Run xrat setup to install everything:

xrat setup

This is idempotent and re-runnable. It checks Xray, sing-box, and V2Ray and can install or update verified user-local copies, runs xrat init, offers to install the background daemon, and installs shell completions, man pages, an xratui shortcut, and (on Linux/XDG) a terminal-aware desktop launcher with icons. Use -y to accept defaults non-interactively, or flags like --no-daemon / --no-desktop to skip individual steps.

To check what is and isn’t configured without changing anything:

xrat setup --check

If you only want individual pieces: xrat init for the config directory and database, xrat daemon install --start for the daemon, or xrat completions <shell> / xrat manpage --output <dir> to print/generate those assets yourself.

Then follow the Quickstart.

Cargo Install

Install xrat with Cargo. Use this path if you already have a Rust toolchain and want cargo-managed installs without the install script.

For release binaries, see Installation Script or Manual Binary Install. To build from a checkout, see Build From Source.

Requirements

• Rust toolchain via rustup (cargo in PATH)
• Xray is required for runtime use; xrat setup can install it and optional sing-box/V2Ray cores as verified user-local tools

Install with cargo-binstall (recommended)

cargo-binstall downloads the matching prebuilt release binary instead of compiling from source, so it’s as fast as the install script but stays inside your Cargo toolchain:

cargo binstall xrat

Install cargo-binstall itself first if you don’t have it:

cargo install cargo-binstall

Install from crates.io (builds from source)

cargo install xrat

Cargo places the binary in ~/.cargo/bin/xrat. Ensure that directory is in PATH:

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

Add that line to your shell startup file if xrat --version cannot find it.

Run Setup

cargo install/cargo binstall only place the binary. Run xrat setup to complete setup — it checks dependencies, runs xrat init, offers to install the background daemon, and installs shell completions, man pages, an xratui shortcut, and (on Linux/XDG) a desktop launcher with icons:

xrat setup

Setup is idempotent and re-runnable. Use -y to accept defaults non-interactively, --no-daemon / --no-desktop to skip steps, or xrat setup --check to report what is and isn’t configured without changing anything.

Then follow the Quickstart.

Update and Uninstall

cargo binstall xrat       # reinstall/upgrade via prebuilt binary
cargo install xrat        # reinstall/upgrade by building from source
cargo uninstall xrat      # remove the Cargo-installed binary

xrat upgrade self-upgrades a release-archive install; for a Cargo-installed binary, prefer cargo binstall xrat or cargo install xrat to update.

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 for runtime use; xrat setup can install it as a verified user-local tool
• sing-box or V2Ray when needed; setup can install these too

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

Build the current checkout and install it through install.sh:

just install

Pass installer flags after the recipe name:

just install --yes

By default, this installs to ~/.local/bin/xrat, plus generated man pages, shell completions, and desktop launcher assets. Override the binary directory with the installer flag:

just install --install-dir /usr/local/bin --yes

Skip desktop launcher assets with the installer flag:

just install --no-desktop --yes

Replace an existing Cargo-installed binary directly with Cargo:

just reinstall

Remove the Cargo-installed binary:

just uninstall

Ensure ~/.local/bin is in PATH for the installer path:

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

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. Existing xrat.1 and xrat-*.1 pages are removed first so renamed or removed commands do not leave stale man pages behind.

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 f00d

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

xrat disable a1b2
xrat enable a1b2

3. Test Connectivity

Test a single config by ref:

xrat test a1b2

Bulk-test all enabled configs:

xrat test --enabled-only --concurrency 4

Skip specific stages:

xrat test a1b2 --skip-icmp --skip-download

4. Start a Proxy

Start the daemon first:

xrat daemon start

Connect using a tested config:

xrat connect a1b2

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:18200
• HTTP on 0.0.0.0:18201 (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 rotate enable
xrat rotate now
xrat rotate status
xrat daemon stop

xrat connect <id> starts one managed runtime session immediately through the daemon. xrat rotate enable 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 = 18203
key = { env = "XRAT_API_KEY" }
pac_enabled = true
pac_allowed_hosts = ["localhost", "127.0.0.1", "::1"]

[runtime]
engine = "xray"
replace_active_session = true

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

[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 = 18200
udp = true
auth = { enabled = true, username = "xrat", password = { env = "XRAT_SOCKS_PASSWORD" } }

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

[runtime.shadowsocks]
enabled = false
host = "0.0.0.0"
port = 18202
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 = []

# Optional Xray outbound tuning (all disabled/empty by default).
[runtime.mux]
enabled = false

[runtime.fragment]
enabled = false

[runtime.network]
interface = ""
listen_interface = ""

[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 = "UseIPv4"
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]
"full:example.test" = "127.0.0.1"

# DNS settings are applied to managed runtimes and Xray probe tests. Xray/V2Ray
# supports the full section; sing-box uses modern typed servers and exact/plain
# or full: hosts. Unsupported sing-box strategies or server/host forms fail
# before launch.

[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
# accepted_status_codes = [200, 204]
# accepted_status_ranges = ["300-399"]
follow_redirects = true

[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

Routing rules affect managed sessions, including daemon rotation, but not connection-test probes. Direct rules are evaluated before block rules. Xray and V2Ray support all four routing lists; sing-box currently supports domain rules and IP/CIDR rules, and rejects geosite/geoip entries until rule-set translation is available.

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 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

xrat init writes a fully documented config file: common settings are active with inline descriptions, and advanced features are present but commented out so the file doubles as offline reference. Default local ports use the 1820x block (SOCKS 18200, HTTP 18201, Shadowsocks 18202, API server 18203).

[runtime]
engine = "xray"
replace_active_session = true

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

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

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

[testing]
concurrency = 0

[server]
enabled = false
host = "127.0.0.1"
port = 18203

See Config File for full reference.

Related

• Quickstart
• Configuration
• daemon install — install as a background service (systemd/launchd/rc.d)

setup

Run post-install setup. setup performs the same work the install script used to script in bash, but in the binary itself, so it works regardless of how xrat was installed (release archive, cargo install, distro package, or manual copy) and can be re-run any time to finish or repair an install.

xrat setup [OPTIONS]

Flags

--check cannot be combined with the mutating flags, and --linger cannot be combined with --no-daemon (linger implies the daemon).

Steps

setup runs these steps in order, each idempotent:

1. Dependencies — checks configured paths and PATH for Xray (required), sing-box, and V2Ray, then compares installed versions with the latest stable official releases. Missing or outdated cores can be installed as user-local managed copies. Declining a missing Xray leaves setup incomplete.
2. init — creates the config directory, config.toml, database, and subdirectories (reuses init; never overwrites a customized config).
3. daemon — installs and starts the background daemon (systemd user service on Linux, launchd agent on macOS, rc.d on BSD). Prompted unless --yes.
4. linger — (Linux) runs loginctl enable-linger so the daemon can start at boot before login. Forced with --linger; otherwise prompted (default no) in interactive runs, and skipped with --yes.
5. completions — generates and installs bash/zsh/fish completions into the standard XDG locations.
6. man pages — generates and installs man pages under $XDG_DATA_HOME/man/man1.
7. desktop — (Linux/XDG) installs a terminal-aware launcher, a .desktop entry, and hicolor icons.
8. xratui — installs an xratui shortcut script next to the xrat binary that execs xrat tui.
9. PATH — checks whether the binary’s directory is on PATH and prints an export hint if not.

Idempotent: re-running reports each step as already done instead of failing. Setup is recorded as a diagnostic event, so a run appears in xrat logs.

Managed cores are installed under $XDG_DATA_HOME/xrat/cores/<engine> (normally ~/.local/share/xrat/cores/<engine>). Setup stores their absolute paths in config.toml and creates CLI links such as ~/.local/bin/xray when that does not overwrite an existing user file. Xray and V2Ray keep separate GeoIP and Geosite assets.

Downloads come from the official Xray-core, sing-box, and V2Ray GitHub stable releases. Setup requires the release asset’s published SHA-256 digest and validates the staged binary’s reported version before replacing a managed copy. It never overwrites an externally installed or package-managed binary; accepting an update for one installs and adopts a managed copy instead. Interactive downloads show byte progress; redirected and machine-readable flows suppress terminal progress rendering.

Example: guided setup

xrat setup -y

Environment
  os           linux
  arch         x86_64
  shell        fish
  terminal     kitty

Dependencies
  ✔ xray         /usr/local/bin/xray (v26.3.27)
  ✔ sing-box     /usr/bin/sing-box (v1.13.13)
  ✖ v2ray        not installed (latest v5.52.0)

Setup
  ✔ init         /home/user/.config/xrat
  ✔ daemon       installed and started
  ✔ completions  3 shells
  ✔ man pages    68 pages
  ✔ desktop      /home/user/.local/share/applications/xrat.desktop
  ✔ xratui       /home/user/.local/bin/xratui
  ✔ PATH         /home/user/.local/bin

OK Setup complete.

Example: diagnose an install

xrat setup --check

  STEP         STATUS        DETAIL
✔ xray         done          /usr/local/bin/xray (v26.3.27)
✔ sing-box     done          /usr/bin/sing-box (v1.13.13)
↑ v2ray        update available /usr/bin/v2ray (v5.48.0; latest v5.52.0; external)
✔ init         already done  /home/user/.config/xrat
✖ daemon       missing       background daemon not installed
✔ completions  already done  -
✔ man pages    already done  -
✖ desktop      missing       desktop launcher not installed
✔ xratui       already done  /home/user/.local/bin/xratui
✔ PATH         done          /home/user/.local/bin

--check exits non-zero when a required step (Xray or init) is missing. An outdated core uses the update_available status but does not fail the check. If the release service is unavailable, an installed core remains usable and the detail column reports that the update check failed. Use --format json for machine-readable output:

xrat setup --check --format json

Relationship to install.sh

The install script downloads, verifies, and places the xrat binary, then runs xrat setup (passing through -y, --no-desktop, and --linger). When the script itself is piped into a shell, it reconnects setup to the controlling terminal so dependency prompts still work. If no terminal exists, use --yes or run xrat setup later.

With --yes, setup installs missing Xray and sing-box, leaves an absent V2Ray alone, and upgrades every outdated core that is already installed.

Related

• init — just the config directory/database step
• daemon install — just the background service step
• completions / manpage — generate scripts to stdout
• Installation Script

import

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

xrat import <input> [--name <name>]

Arguments

Options

Input Formats

xrat automatically detects the input format:

Examples

Import from a subscription URL:

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

Import and name a subscription:

xrat import https://example.com/sub.txt --name "Work VPN"

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 and applies --name when provided
7. Reconciles the source: configs attached to the same subscription that are absent from this payload are soft-deleted (recoverable). A later import that brings them back restores them. An empty payload removes nothing.
8. Prints an import summary, including the count of removed configs

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.

update

Refresh stored subscriptions.

xrat update [SUBS_REF...]

If no refs are provided, xrat refreshes all subscriptions with stored source values. If refs are provided, xrat refreshes only matching subscriptions (numeric IDs and stable ref prefixes are both accepted).

Examples

Refresh all subscriptions:

xrat update

Refresh selected subscriptions:

xrat update 7 feedbeef

Config Management Commands

Manage individual stored configs after import.

These commands operate on config refs from xrat list configs. Numeric IDs are still accepted for compatibility.

When to Use These Commands

Config State

active, enabled, and deleted are separate states.

Use xrat connect <ref> when you want to start a proxy runtime. Use xrat rotate enable 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 or subscription. The target is a required subcommand (config or subscription).

xrat show config <ref> [--json]
xrat show subscription <ref> [--json]

Arguments

Flags

Examples

xrat show config a1b2
xrat show config a1b2c3d4 --json
xrat show subscription f00d

enable

Enable a config.

xrat enable <ref>

Arguments

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

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

enable/disable are idempotent: enabling an already-enabled config (or a deleted one) prints an informational notice and exits successfully without changing state.

disable

Disable a config.

xrat disable <ref>

Arguments

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

delete

Delete a config (soft by default) or a whole subscription. The target is a required subcommand (config or subscription).

xrat delete config <ref> [--hard]
xrat delete subscription <ref> [--yes]

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 delete config --hard only when the row should be permanently removed. delete subscription permanently removes the subscription and all of its configs (plus their test history and runtime sessions), so it prompts for confirmation unless --yes is given.

restore

Restore a soft-deleted config.

xrat restore <ref>

Arguments

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

purge

Permanently delete all soft-deleted configs in one step, along with their test history and runtime sessions.

xrat purge [--yes]

Flags

purge reports how many configs are pending and prompts for confirmation before deleting. In a non-interactive shell it aborts unless --yes is given. This is irreversible — restore anything you want to keep with xrat restore first.

xrat purge          # prompts: Permanently delete N soft-deleted config(s)? [y/N]
xrat purge --yes    # no prompt

Related

• stable refs — use short refs in place of numeric IDs
• list — find config refs and filter by state
• runtime — connect, disconnect, and inspect active sessions
• tui — manage configs interactively

Stable Refs

xrat stores numeric database IDs internally, but user-facing commands use stable short refs for configs and subscriptions.

Refs are random lowercase hex strings generated on insert. Human output shows the first 8 characters by default:

REF       STATUS          PROTO  ADDRESS          PORT  NAME
a1b2c3d4  enabled,active  vless  example.com       443  Main

You can use any unique prefix:

xrat connect a1b2
xrat show config a1b2c3d4
xrat test a1b2
xrat delete subscription f00d

Numeric IDs still work as command input for compatibility:

xrat connect 42

If a prefix matches more than one row, xrat asks for more characters. If a numeric string matches an existing numeric ID, the numeric ID wins; otherwise xrat tries it as a ref prefix.

Commands that accept config refs include connect, show config, enable, disable, restore, delete config, test <ref>, and rotate now --config-id.

Commands that accept subscription refs include show subscription, delete subscription, list configs --subscription, and test --subscription.

validate

Validate that an XRAT config.toml file exists, parses, and is internally consistent.

xrat validate <path> [--format <human|json>]

A path is required. The command does not modify anything; it only reports whether the file is valid.

Flags

What it checks

Enum-backed fields ([testing].order, [testing].failure_policy, [database].backend, GeoIP backend/provider settings) and integer duration fields are checked against the raw config file before it is deserialized, so an invalid value or wrong type is reported against the specific field instead of a generic parse failure.

• Runtime: engine is one of xray, v2ray, sing-box; rotation test_concurrency is non-negative; rotation test_stages only contains known stage names (icmp/ping, real_delay, download, tcp, and their aliases); enabled inbounds have a host and a non-zero, non-duplicated port; SOCKS auth and Shadowsocks material are present when enabled.
• Database: when backend = "postgres", validates user, database name, connection-pool bounds, and connect timeout.
• Testing: concurrency is non-negative; [testing].order has no duplicate stages; enabled probes have valid HTTP/HTTPS URLs and positive timeouts.
• Server: when enabled, host is present and any API key is structurally valid.

Secret references

Secret values such as passwords and API keys can be inline literals or environment references ({ env = "VAR_NAME" }). Validation is structural: a literal must be non-empty and an env reference must name a variable, but the environment variable is not required to be set at validation time. Actual resolution happens at runtime.

Diagnostics

Each validation error is reported as a diagnostic with four parts: the offending field, the problem with its value, the reason the constraint matters, and a fix that includes accepted values or ranges. Both human and json output carry the same information, so structured consumers get the same repair guidance as the terminal.

Examples

xrat validate config.toml

OK config.toml is valid.

Human output for an invalid config:

config.toml has 1 validation error(s):

  [runtime].engine unsupported engine: bad
    why: the engine selects which proxy core generates and runs the runtime config.
    fix: use one of: xray, v2ray, sing-box.

Machine-readable output:

xrat validate --format json config.toml

{
  "path": "config.toml",
  "valid": false,
  "errors": [
    {
      "field": "[runtime].engine",
      "problem": "unsupported engine: bad",
      "reason": "the engine selects which proxy core generates and runs the runtime config.",
      "fix": "use one of: xray, v2ray, sing-box."
    }
  ]
}

Exit status

Returns a non-zero exit code when the config is invalid, so it can be used in scripts and CI.

Related

• config management — edit and inspect the active config
• init — create a starter config.toml

list

List stored configs or subscriptions.

xrat list <target> [flags]

Targets

list configs

xrat list configs [flags]

Flags

Examples

List all configs:

xrat list configs

List only enabled configs from a subscription ref:

xrat list configs --enabled-only --subscription f00d

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

Human tables show short refs first. Use --format tsv or --format json for scripts; those formats use stable refs and omit internal numeric database IDs. The default table format is optimized for humans and may change as the CLI evolves.

Subscription output includes an updated_at timestamp in all formats so you can see the latest refresh/import time at a glance.

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 [ref] [flags]

Arguments

Filter Flags

When testing multiple configs (no ref 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, TCP, real-delay, and download is configurable via config.toml. TCP is opt-in as a standalone stage; without it in order, TCP still runs as an implicit gate before real-delay when [testing.tcp].enabled is true.

[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 a1b2

Bulk-test all enabled configs with 4 workers:

xrat test --enabled-only --concurrency 4

Test with custom URLs and timeouts:

xrat test a1b2 \
  --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 a1b2 --skip-icmp --skip-download

Export results to CSV:

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

Continuous ping loop:

xrat test a1b2 --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

Table (default)

Aligned human-readable table for terminal use.

TSV

Tab-separated values for scripts:

ref	name	protocol	address	port	icmp_ms	real_delay_ms	download_mbps	upload_mbps	status	error
a1b2c3d4	Primary	vless	example.com	443	15	145			ok
f00d1234	Edge	vmess	edge.com	8443					failed	timeout

CSV

Comma-separated values, spreadsheet compatible.

JSON

Machine-parseable JSON array with full test result details.

Dial-endpoint GeoIP columns

When GeoIP is enabled, each tested config records geolocation for the address it dials. These columns appear only when at least one tested config resolved GeoIP data, so non-GeoIP runs stay compact.

These describe the dial endpoint — the address xrat connects to first — not a verified proxy origin. When the dialed address is behind a CDN or relay, the country and ASN belong to that fronting provider, and dial_endpoint_fronting names the detected provider (a hint, not proof of the backend location). dial_endpoint_geoip_source records lookup provenance: literal_ip when the config dialed a literal IP, dial_dns when a hostname was resolved via DNS.

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
xrat scan --history 20 --format json

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

Normal scans print a concise persistence summary. --history prints an aligned table by default; use --format tsv or --format json for scripts.

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 <ref> [flags]

Arguments

Flags

Examples

xrat connect a1b2

xrat connect a1b2c3d4 --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 uses Xray/V2Ray for protocols they can generate. Hysteria2 (hy2) configs are sing-box-only, so xrat connect automatically launches the configured sing-box binary for those configs even when [runtime].engine is xray. Setting [runtime].engine = "sing-box" for non-Hysteria2 configs currently returns a clear unsupported-combination error.

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,
  "session_config": {
    "ref": "a1b2c3d4e5f6"
  },
  "protocol": "vless",
  "address": "example.com",
  "port": 443,
  "pid": 12345,
  "pid_alive": true,
  "socks_port": 18200,
  "socks_reachable": true,
  "http_port": 18201,
  "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

logs

Show a unified view of application events and proxy engine logs.

xrat logs [flags]

xrat logs merges two sources:

• App events — structured rows recorded in the database (events table): daemon start/stop, runtime connect/disconnect, proxy rotation, health failover, and test runs.
• Engine logs — the stdout/stderr of the xray-core / sing-box process for the active or most recent runtime session, plus the daemon’s own daemon.log file.

By default it prints the last N entries and exits. Use --follow to stream new entries live (press Ctrl-C to stop).

Flags

Notes:

• --format json / --format tsv emit the structured app events only; engine/daemon text logs are unstructured and are shown only in the default table view or while following.
• --source xray / --source singbox tail the engine log files for the active or last session; --source daemon tails daemon.log; --source app shows only structured events.
• Engine logs are parsed into TIME / LEVEL / SOURCE / MESSAGE columns (xray and sing-box), matching the TUI engine tab. Access logs from xrat’s own stats polling of the api inbound ([api -> api]) are filtered out as instrumentation noise.

Examples

# Last 200 events plus engine log tails
xrat logs

# Live stream everything
xrat logs -f

# Only the last 50 lines of xray-core output
xrat logs --source xray -n 50

# Only error-level app events, as JSON
xrat logs --source app --level error --format json

Clearing persisted events

xrat logs clear [--yes]

xrat logs clear permanently deletes every row from the events table. It prompts for confirmation first; pass --yes to skip the prompt (useful in scripts). This only clears the structured app events in the database — engine and daemon log files are left untouched, since they rotate with their runtime sessions.

The TUI exposes the same database clear from the logs card via the C p clear chord, kept distinct from any view-only buffer clears.

# Wipe all recorded app events without a prompt
xrat logs clear --yes

Where logs live

The daemon emits its own process output to daemon.log (errors and panics); normal operational events are captured as structured rows instead.

Related

• daemon — start/stop the supervisor that records most events
• proxy — auto-rotation, a frequent source of events
• runtime — connect, disconnect, and inspect active sessions

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 restart

Restart the daemon after editing config.toml.

xrat daemon restart

Flags

No command-specific flags.

Behavior

1. If the daemon is running, requests shutdown via IPC and waits for the socket to close
2. Spawns a fresh daemon process, which re-reads config.toml and reattaches the persisted runtime session
3. If the daemon was not running, simply starts it

Restart always uses the app IPC/start flow, even when a systemd user service is installed, so behavior stays consistent across manual and service-managed daemons.

daemon install

Install xrat as a background service. The service manager is selected by operating system:

On FreeBSD/OpenBSD the rc.d script is system-wide and enabling/starting it requires root (run under sudo), unlike the per-user systemd and launchd paths.

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

Flags

Behavior (Linux/systemd)

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

macOS and BSD follow the same shape with their templates (packaging/launchd/, packaging/rc.d/): generate the unit, write it to the service location, register it (launchctl bootstrap / sysrc+service / rcctl enable), and start it when --start is passed.

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 background service (systemd/launchd/rc.d depending on the OS).

xrat daemon uninstall [--dry-run]

Flags

Behavior (Linux/systemd)

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

macOS and BSD perform the equivalent stop/disable/remove with their service managers (launchctl bootout / service stop+sysrc / rcctl).

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

• rotate — control auto-rotation scheduling
• proxy — local proxy endpoints, shell, desktop, and PAC helpers
• 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

db

Inspect and maintain the XRAT database.

xrat db <action>

Actions

db migrate

xrat db migrate

Applies any pending schema migrations and confirms the database is up to date.

Migrations normally run automatically on the first command after an upgrade and during xrat upgrade itself. This command makes that step explicit, which is useful for:

• Verifying the database is current after a manual binary swap.
• Surfacing a migration error on demand with actionable context.

Output

OK Database migrations are up to date.

Migration errors

If a migration fails, the error names the migration version, the likely cause, and recovery guidance. Common cases:

• Checksum mismatch — a previously shipped migration file was edited after release. Restore the original migration (reinstall the matching release) or reset the database from a backup.
• Dirty / partially applied — inspect the _sqlx_migrations table, finish or revert the offending migration by hand, and remove its row before retrying.
• Missing migration — the database records a migration this build does not contain, usually after a downgrade. Upgrade back to a build that includes it.

Contributor policy: never edit a migration that has already shipped in a release. sqlx stores a per-migration checksum in _sqlx_migrations; editing a released migration changes its embedded checksum and breaks upgrades for existing databases. Always add a new ordered migration instead.

Related

• upgrade — runs migrations as part of self-upgrade
• init — create the database before first use

rotate

Control automatic proxy rotation scheduling via the daemon.

xrat rotate <action> [flags]

All rotate actions require a running daemon:

xrat daemon start

Rotation scheduling moved here from the old xrat proxy start|status|stop commands. The proxy namespace now covers local proxy endpoints and host/ session integration; see proxy.

Actions

rotate enable

Enable automatic proxy rotation on a fixed schedule.

xrat rotate enable

The daemon enables the rotation scheduler using [runtime.rotation] settings from config.toml (interval, health trigger, threshold, and cooldown). The command also writes runtime.rotation.enabled = true atomically, so the choice survives daemon restarts.

rotate disable

Disable automatic proxy rotation. The active proxy session keeps running; only the scheduler is disabled.

xrat rotate disable

The command writes runtime.rotation.enabled = false atomically. It does not disconnect the active runtime.

rotate status

Show the current rotation status.

xrat rotate status [--json]

Flags

rotate now

Trigger an immediate manual rotation.

xrat rotate now [--config-id <ref>] [--refresh]

Flags

Behavior

1. If --refresh is provided, re-fetches URL-backed subscriptions before anything else, so the candidate pass sees the freshest configs.
2. If --config-id is provided, rotates to that specific config.
3. Otherwise, selects the best candidate from enabled configs:
   • Runs fresh tests using test_stages from config.toml; stored results are not reused.
   • Uses real-delay as the qualifying metric when run, then download, then TCP. ICMP is diagnostic and cannot qualify a candidate alone.
4. Runs the selected engine’s native config validator before stopping the old session.
5. Starts the replacement on the same configured local inbound ports. If that post-stop handoff fails, xrat attempts to restore the previous runtime.

An explicit --config-id bypasses candidate testing and cooldown, but the config must be enabled, different from the active config, and pass native preflight validation. An unpinned manual rotation bypasses cooldown but still runs fresh candidate tests.

Related

• proxy — local proxy endpoints, shell, desktop, and PAC helpers
• daemon — daemon must be running for rotation
• connect — start one proxy session through the daemon
• test — test configs before enabling rotation

proxy

Local proxy endpoints and host/session integration helpers.

xrat proxy <action> [flags]

Automatic rotation scheduling moved to the rotate command. The old xrat proxy start|status|stop rotation commands have been removed.

Actions

proxy info

Show active local proxy endpoints for the current runtime.

xrat proxy info [--json]

Lists the active runtime inbounds (HTTP, SOCKS5, Shadowsocks) plus the PAC URL when [server].enabled = true and [server].pac_enabled = true. If an inbound binds 0.0.0.0, the machine LAN IP is shown for easy local-network use; otherwise the configured bind host is shown.

Shadowsocks credentials are not persisted in runtime status, so the Shadowsocks line shows only the endpoint with a (credentials not shown) note rather than a leaky partial ss:// URI.

xrat proxy show and xrat proxy endpoints are accepted as aliases.

Flags

proxy pac

Work with a Proxy Auto-Config (PAC) file generated from the active runtime endpoints, so browsers and desktop environments can use per-destination routing instead of a blunt global proxy.

xrat proxy pac url     # print the PAC URL served by the API server
xrat proxy pac print   # print the generated PAC file for the active runtime

proxy pac url

Prints the URL the API server serves the PAC file at, for example http://127.0.0.1:8787/proxy.pac. A wildcard bind host (0.0.0.0) is shown as 127.0.0.1, since PAC consumers should fetch over loopback. If the API server or PAC route is disabled, a note explains which [server] setting to enable.

proxy pac print

Generates the PAC file locally from the active runtime’s HTTP/SOCKS inbounds and prints it to stdout. The generated PAC:

• Routes plain hostnames, *.local, loopback, and private IP ranges DIRECT.
• Applies curated [routing.direct] and [routing.block] domain entries and IPv4 CIDRs from ip lists in that order.
• Prefers SOCKS, then HTTP, for everything else; no DIRECT fallback is added while a proxy is active.
• With no active runtime, routes everything DIRECT.
• Rewrites wildcard inbound hosts like 0.0.0.0 to 127.0.0.1 because PAC clients need a concrete proxy destination.
• Resolves hostnames before private IPv4 CIDR checks and skips those checks when DNS resolution fails.

PAC generation does not inline geosite or geoip lists; those stay in the proxy engine config.

PAC route

The PAC file is also served by the Axum API server at:

GET /proxy.pac

This route is unauthenticated by default and returns Content-Type: application/x-ns-proxy-autoconfig. PAC consumers usually cannot send auth headers, and the file exposes only non-secret local endpoint data (Shadowsocks credentials are never included). Prefer a loopback server bind for PAC use. Set [server].pac_enabled = false to disable this route. Requests are accepted only when the HTTP Host header matches [server].pac_allowed_hosts, which defaults to localhost, 127.0.0.1, and ::1.

proxy shell

Proxy only the current terminal session and its child processes, without changing desktop or system proxy settings. xrat prints shell commands; it never edits .bashrc, .zshrc, or fish config.

xrat proxy shell enable [protocol] [--shell bash|zsh|fish]
xrat proxy shell disable [--shell bash|zsh|fish]
xrat proxy shell toggle [--shell bash|zsh|fish]
xrat proxy shell status

enable sets http_proxy/https_proxy (prefer the HTTP inbound, falling back to SOCKS) and all_proxy (prefer SOCKS, falling back to HTTP), plus their uppercase variants. It errors if no usable inbound is active. disable unsets those variables. status inspects the environment inherited by xrat and reports whether the current shell points at active xrat endpoints.

enable, disable, and toggle also print the resulting proxy shell status to stderr after emitting their script, so the stdout script stays safe to eval/ source unchanged. Since xrat cannot inspect the parent shell after the script runs, this status is derived from the emitted action and saved toggle values. Each script starts with a # comment showing how to apply it for the detected shell (or the one selected with --shell). The same usage note appears in each subcommand’s --help.

Protocol

enable accepts an optional trailing protocol to force the scheme used for both http_proxy/https_proxy and all_proxy:

When omitted, the default behavior applies: http_proxy/https_proxy prefer the HTTP inbound, all_proxy prefers SOCKS, with cross-fallback. An explicit protocol never falls back: if its matching inbound is not active, xrat reports the config setting to enable and suggests omitting the protocol for automatic selection. Reconnect the runtime after enabling an inbound.

Usage

bash/zsh — a child process cannot mutate its parent shell’s environment, so eval the output:

eval "$(xrat proxy shell enable)"
eval "$(xrat proxy shell disable)"

fish — source from a pipe:

xrat proxy shell enable | source
xrat proxy shell disable | source

Optional convenience aliases (xrat does not create these for you):

alias xrat-proxy-on='eval "$(xrat proxy shell enable)"'
alias xrat-proxy-off='eval "$(xrat proxy shell disable)"'
alias xrat-proxy-toggle='eval "$(xrat proxy shell toggle)"'

Shell detection

The shell is detected from $SHELL, then the parent process name, defaulting to bash. Override with --shell bash|zsh|fish.

Shell toggle

toggle prints shell commands. Use eval "$(xrat proxy shell toggle)" for bash/zsh or pipe to source in fish.

When enabling, it captures the current proxy variables in temporary XRAT_PROXY_OLD_* / XRAT_PROXY_HAD_* variables before exporting the active xrat endpoints. When the shell already points at active xrat endpoints, the next toggle restores the captured values or unsets variables that were absent.

proxy desktop

Desktop/system proxy integration. This changes the desktop environment (Linux) or system network service (macOS) proxy settings, not every process on the system. The backend is selected by operating system:

xrat proxy desktop enable [--desktop gnome|kde|xfce] [--pac]
xrat proxy desktop disable [--desktop gnome|kde|xfce]
xrat proxy desktop toggle [--desktop gnome|kde|xfce] [--pac]
xrat proxy desktop status [--desktop gnome|kde|xfce]

On Linux the desktop is auto-detected from $XDG_CURRENT_DESKTOP / $DESKTOP_SESSION; override with --desktop. GNOME is supported through gsettings:

• enable sets manual HTTP/HTTPS/SOCKS proxies from the active runtime by default and does not require PAC. With --pac, it switches to automatic mode using the PAC URL; PAC mode requires both [server].enabled = true and [server].pac_enabled = true.
• disable resets the proxy mode to none.
• toggle enables manual HTTP/HTTPS/SOCKS settings when the current mode is none; with --pac, it uses PAC only while turning proxy on. If the current mode is not none, it disables without requiring PAC.
• status prints the current proxy mode.

KDE and XFCE are not supported yet and return a clear error suggesting xrat proxy shell enable for terminal-only proxying. The --desktop flag is ignored on macOS.

On macOS the same verbs apply to every enabled network service (Wi-Fi, Ethernet, …) via networksetup: enable sets the web, secure, and SOCKS proxies (or the PAC URL with --pac), disable turns all of them off, status reports the per-service web/socks proxy state, and toggle flips based on the current state.

desktop is used rather than system because there is no single universal system proxy authority across platforms.

Related

• rotate — automatic rotation scheduling
• daemon — daemon must be running for runtime operations
• connect — start one proxy session through the daemon
• serve — run the API server that hosts /proxy.pac

mmdb

Manage GeoLite2 MMDB assets and inspect GeoIP lookup configuration.

xrat mmdb <command> [flags]

Subcommands

download

Download one or more GeoLite2 MMDB editions.

xrat mmdb 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 mmdb download --all

Download a single edition:

xrat mmdb download --edition city

Download to a custom directory:

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

update

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

xrat mmdb update [flags]

Example

xrat mmdb update

path

Print the resolved MMDB directory.

xrat mmdb 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 mmdb path
xrat mmdb path --output /custom/path

status

Show MMDB presence and size for each supported edition.

xrat mmdb status [flags]

Example

xrat mmdb status --strict
xrat mmdb status --json

lookup

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

xrat mmdb lookup <ip> [flags]

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

Examples

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

backend

Print the active GeoIP backend configuration.

xrat mmdb backend [flags]

Shows lookup backend, fallback, cache settings, remote provider settings, and local MMDB paths.

Example

xrat mmdb backend

Troubleshooting

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

xrat mmdb download --all

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

xrat mmdb path
xrat mmdb 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 = 18203
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,
    "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,
      "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,
  "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

xrat setup also installs an xratui shortcut next to the xrat binary (run automatically by install.sh/just install, or manually after cargo install/cargo binstall):

xratui

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, subscription, testing, and runtime 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.

Tabs

The TUI is a single dashboard. The top-left table has two tabs; switching the tab also swaps the detail panel on the right. The Testing strip, the Logs panel, and the Runtime panel stay visible under both tabs.

Use [ and ] to move to the previous / next tab.

The TUI opens on the Configs tab. The bottom bar shows the version (with an upgrade hint when a newer release is available) and a help shortcut. Test batches are started and monitored from the Configs tab itself; there is no separate Tests view.

Global Keys

Cards and Scrolling

The dashboard has four cards: the table (Configs/Subscriptions), Logs, the detail panel, and Runtime. Card titles show their direct focus shortcuts (1:, 2:, 3:, 4:). Tab / Shift+Tab move focus between them; the focused card is drawn with an accent border. j/k (or the arrow keys) move the row selection when the table is focused, and scroll the focused card otherwise. PgUp/PgDn step by a screenful and Home/End jump to the first/last row or top/bottom of the card. Cards that overflow their height show a scrollbar.

In the Logs card, long messages wrap inside the message column and continuation lines stay indented under it, so the time, level, source, and kind columns stay aligned and one entry never blends into the next.

Settings Modal

Press , from either tab to edit operational values from the active config.toml, including runtime and inbound settings, rotation, tests, subscription refresh, routing, the API server, and parser mode. Fixed DNS options are editable and take effect on the next managed-runtime restart. Database, binary paths, dynamic [dns.hosts] entries, and Geo/MMDB asset management remain file-only settings. Engine-specific DNS limitations are reported when a runtime configuration is generated.

The modal shows a two-level setting tree on the left and effective values on the right. Deeper groups share their parent page under subheaders such as General, Authentication, Cache, and Remote. Use Left/Right, Enter, or Tab/Shift+Tab to switch panes, then j/k or Up/Down to navigate the active pane. Use / to filter, Enter to edit or toggle, h/l to cycle choices, and r to remove an explicit override and return to its built-in default. List fields use comma-separated values. Secret fields stay masked; enter a literal replacement or env:VARIABLE_NAME. Ctrl+S validates and saves without closing the modal, while Esc cancels the current edit or closes the modal. Closing with unsaved changes asks for confirmation. On compact terminals, only the focused Sections or Values pane is shown; use Left and Right to switch between them.

A contextual Help pane follows the selected field. It explains what the field controls, shows its accepted values or input format, provides a safe TOML assignment example, and states whether the change applies live or needs a proxy runtime or daemon restart. It also shows the built-in default and whether the current value is inherited or explicitly configured. Value rows use · for an inherited default, + for an explicit override, and * for an unsaved change; the Help pane includes the same legend. Secret examples use safe placeholders (and environment-variable references where supported) and never display configured secret contents.

Saving patches only changed keys, preserving comments and unrelated sections. New values apply to subsequent TUI tests and connections immediately. Changes to runtime or routing generation offer to restart an active proxy after saving; daemon-owned rotation, subscription-refresh, and API-server settings report that the daemon must be restarted.

Configs Tab

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

Chord keys

On the Configs tab, t, d, D, and r are chord leaders: press the leader, then a second key to pick the scope. The key bar shows the available second keys while a chord is armed; Esc (or any unbound key) cancels it. Every destructive action — single-row (d d, D D, r r) and multi-config alike — asks for an inline y/n confirmation in the key bar; there are no confirmation modals. Multi-config chords run as a single bulk database operation.

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

The config detail panel shows the subscription a config belongs to (#id name) or none for configs added directly. The Configs table title shows the active subscription filter (· sub:<name> or · sub:orphans) when one is set from the Subscriptions tab.

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

The Runtime panel shows the current managed runtime state, active config, current task, proxy endpoint, available proxy engines (xray / sing-box), daemon status and rotation schedule, config counts, and failure message when present. The API subscription URL is shown only when the HTTP API is enabled; when the API binds to 0.0.0.0/:: the panel shows the host’s LAN IP instead of the wildcard address. 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.

Focus a config on the Configs tab and press Enter to start or switch the runtime. Runtime operations run in the background and reload TUI data after completion.

Subscriptions Tab

The Subscriptions tab replaces the Configs table with the subscription list; the right Detail panel then shows the focused subscription’s metadata. The local HTTP API base64 subscription URL is shown in the Runtime panel.

The table starts with two synthetic rows that act as filters for the Configs tab:

• All configs — clear the subscription filter; the Configs tab shows every config.
• Orphans — show only configs that do not belong to any subscription (for example, configs added with xrat add).

Below them is one row per subscription. Focusing any row applies its filter to the Configs tab live, with no confirmation step; switch back to the Configs tab to browse the filtered set.

Subscription actions apply to the focused subscription row; they are no-ops on the All configs and Orphans rows.

Press i from either tab to open the import modal, then paste one supported config share link or one HTTP(S) subscription URL. Config links are saved immediately. Subscription URLs open a second, compact name prompt; leaving it blank uses the displayed random name. File paths, raw base64 payloads, JSON, and multi-link text remain available through xrat import <input>.

Subscription refresh runs as a background task. While it runs, the Runtime card shows live activity and the bottom bar shows completion summaries that auto-hide. When refresh finishes, the TUI reloads database-backed data so both tabs reflect the new state, including any configs removed by subscription reconciliation.

Testing Strip

A full-width Testing strip sits below the filter bar under both tabs. Its left side summarizes the test scope and count, mode, and concurrency. Its right side shows a live progress gauge while a batch is running, then summarizes nonzero completed result counts as done, ok, and failed.

Test batches run the stages listed in [runtime.rotation].test_stages (typically icmp and real_delay) with concurrency 4, restricted to enabled, non-deleted configs. TCP and upload stages are always skipped from the TUI; the URLs, timeouts, and other stage settings come from config.toml. This mirrors rotation’s stage selection rather than the full xrat test pipeline — for a CLI bulk test with identical semantics, run xrat test --enabled-only and align [testing] stages with [runtime.rotation].test_stages. Tests use the t chord leader: t t (focused), t a (all enabled), t v (visible), t r (failed), t s (stale), and t c cancels a running batch.

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

Runtime, Logs, and Help

The merged runtime panel summarizes runtime, database, subscription, API, and config-count state alongside the active config. Both the runtime and logs cards stay visible under both tabs.

The Logs card is tabbed. Focus it with 2, Tab, or Shift+Tab, then switch tabs:

The Engine and Traffic tab titles show the active engine and version.

The engine tab parses recognized xray and sing-box log lines into time, level, source/component, and message columns; the active engine and version are shown once in the card title instead of repeating per row. Generated sing-box configs enable log.timestamp so its lines carry a timestamp. xray access logs get an inferred Info level and their [inbound >> outbound] routing path in the source column. stderr is styled as a warning, and unrecognized lines are kept as raw messages with severity inferred from keywords. Access logs from xrat’s own stats polling ([api -> api]) are hidden as instrumentation noise, the same as xrat logs.

The API tab splits each recorded request into TIME, LEVEL, METHOD, PATH, CODE, and MESSAGE columns. The server records requests as the synthetic line <METHOD> <path> -> <code>, which is not a real handler message, so MESSAGE shows -; any recorded line that is not a request line is shown verbatim.

Severity colors are shared across the Events, API, and Engine tabs: critical/fatal/panic/error are red, warn/warning are yellow, and info/debug/trace are neutral/accent.

The Traffic tab samples the active engine once per second — the xray gRPC StatsService or the sing-box Clash API /connections endpoint — and resets its history on each new runtime session. It is enabled by [runtime.stats] (see config reference). The top row shows a throughput summary (total ↓/↑ and current rate) next to a probe table (Name | Value | mean ± std | n | last update) built from the active config’s recent connection_tests. The lower row pairs a bidirectional traffic chart (upload bars up, download bars down, with independent scales and failure markers) with a probe-latency graph plotting each activated latency test as its own colored series.

Clears come in two kinds. C l and C s are view-only: they hide the current log/traffic buffer in the TUI without deleting anything, and a periodic reload does not resurrect the cleared rows. C p is a database clear — it removes the persisted events rows, the same data cleared by xrat logs clear. Engine log files are not touched by any of them.

Press ? from either tab to open the help modal. Press Esc to close it.

QR and Clipboard Behavior

QR modals are available for focused config URIs, subscription 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 subscription/API QR or copy actions report that a URL is unavailable, ensure the subscription 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

upgrade

Self-upgrade the running xrat binary, either by downloading the latest GitHub release (default) or by building from a local source checkout.

xrat upgrade [OPTIONS]

The new binary is staged in the same directory as the current executable and then atomically renamed over it, so an in-place upgrade is safe even while the command is running. Upgrade discovery and installation run before database initialization, allowing xrat upgrade to recover from a database migration or connection failure. The newly installed binary still runs migrations before the command reports success.

Flags

Release upgrade (default)

xrat upgrade

1. Queries the latest GitHub release tag (or uses --version).
2. If the current binary already matches, prints already using latest version and exits without downloading. Use --force to reinstall anyway.
3. Downloads the matching xrat-<version>-<arch>.tar.gz archive with a progress bar, verifies it against SHASUMS256.txt, extracts the binary, and replaces the running executable.
4. Runs database migrations with the newly installed binary so any migration failure is reported as part of the upgrade instead of surfacing on the next unrelated command. If migrations fail, see db migrate for recovery details.

Prebuilt archives are available for Linux (x86_64 and aarch64, musl) and macOS (x86_64 and aarch64, darwin). On other platforms or architectures (including FreeBSD/OpenBSD), use --source.

xrat upgrade --version v0.2.1 --force

Build from source

xrat upgrade --source            # builds from the current directory
xrat upgrade --source --path ~/code/xrat

Runs cargo build --release in the source directory, then installs the produced target/release/xrat over the running binary. Requires cargo on PATH and a Cargo.toml in the source directory.

Notes

• Replacing a binary in a system directory (for example /usr/local/bin) may require elevated permissions; rerun with sudo if you hit a permission error.
• Only the binary is replaced. Man pages and shell completions are not updated; rerun install.sh if you want those refreshed too.

Related

• Installation Script
• Build From Source

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 for supported Xray/V2Ray protocols
• sing-box — sing-box JSON preview plus managed Hysteria2 runtime sessions through xrat connect

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.

Refreshing Subscriptions

Re-importing a URL-backed subscription is a reconciliation, not an additive import: configs the provider still returns are upserted, and configs that disappeared from the payload are soft-deleted (recoverable; a later re-add restores them). An empty payload removes nothing. See Deduplication for the dedup key used to match configs.

There are two ways to refresh:

• Manual — run xrat update (or xrat update <ref...>), re-run xrat import <url>, or press r / R on the TUI Subscriptions tab. Available any time, no daemon required.

• Automatic — the daemon periodically re-fetches URL-backed subscriptions on a fixed interval. Configure it under [subscriptions]:

  [subscriptions]
  auto_refresh = false
  refresh_interval_hours = 24
  

  When auto_refresh is enabled, the daemon refreshes each URL-backed subscription whose last_refreshed_at is older than refresh_interval_hours (or that was never refreshed). Because the due check reads the persisted last_refreshed_at, intervals survive daemon restarts. Non-URL sources (files, raw text) are skipped, and a failed fetch is recorded as an event without stopping the daemon or the rest of the batch. Refresh start, success, and failure are visible in xrat logs.

  Automatic refresh requires a running daemon (xrat daemon install --start). Manual refresh uses the exact same import + reconciliation path.

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
# Omit both fields to accept 200-299.
# accepted_status_codes = [200, 204]
# accepted_status_ranges = ["300-399"]
follow_redirects = true

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

Stage Order

The order array controls ICMP, TCP, real-delay, and download ordering. Accepted values: icmp, tcp, real_delay, download. When real_delay is present and tcp is not, TCP still runs as an implicit gate before real-delay when [testing.tcp].enabled is true. Listing tcp explicitly makes it a standalone stage and avoids running the same TCP check twice if both tcp and real_delay are present. 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 the system ping command with platform-specific count and timeout flags, then 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
accepted_status_codes = [204]
accepted_status_ranges = ["300-399"]
follow_redirects = false

When either acceptance field is present, it replaces the default 200-299 range. Exact codes and inclusive START-END ranges are combined with OR semantics, so the example accepts 204 or any status from 300 through 399. Codes and range endpoints must be within 100-599.

With follow_redirects = true, xrat follows up to 10 redirects and checks the terminal response status. A loop or longer chain fails the test. With follow_redirects = false, xrat checks the first response, allowing an initial 3xx response to pass when configured; later redirect behavior, including a possible loop, is intentionally not inspected.

The [dns] settings are applied to the Xray probe configuration used by real-delay, download, and upload tests. This controls how Xray resolves the remote test endpoint through the proxy. The DNS block is omitted when all DNS settings have their defaults. ICMP and TCP stages are direct checks and do not use this configuration.

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. When [dns] is non-default, the generated JSON also contains the configured Xray dns object:

{
  "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 a1b2 --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 a1b2 --ping --ping-interval 2000

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

Ping loop for config a1b2 (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 mmdb 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 describe the dial endpoint — the address xrat actually connected to. For configs that front through a CDN or relay, this is the front door, not necessarily the proxy’s real origin:

• dial_endpoint_ip — resolved IP address
• dial_endpoint_country — ISO country code (e.g. NL)
• dial_endpoint_location — location label such as city/country when available
• dial_endpoint_asn — Autonomous System Number and organization (e.g. AS15169 Google LLC)
• dial_endpoint_geoip_source — lookup provenance: literal_ip (the config dialed a literal IP) or dial_dns (a hostname resolved via DNS, where CDN fronting hides)
• dial_endpoint_fronting — detected CDN/relay provider label (e.g. cloudflare) when the dialed IP belongs to a known fronting network. This is a hint, not proof: the real origin may be elsewhere or hidden. null when no fronting provider is recognized.

Because these fields describe the dial endpoint, the --country/--asn filters on xrat test --latest-run-summary match the fronting/relay provider for fronted configs, not the verified origin.

Related

• mmdb 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": 18200,
      "listen": "0.0.0.0",
      "protocol": "socks",
      "settings": { "udp": true }
    },
    {
      "tag": "http-in",
      "port": 18201,
      "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 a1b2

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 the process executable and command line (queried via sysinfo, so it works across Linux/macOS/BSD) with the expected runtime engine and session config
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, then auto-recover

Stale PID Recovery After Reboot

A dead PID is the common case after a reboot: the persisted session points at a proxy process that no longer exists. Rather than leaving the runtime stopped and forcing a manual reconnect, the daemon clears the stale attachment and relaunches the persisted config automatically (when it is still enabled and not deleted).

Recovery is recorded as an event visible in xrat logs:

• daemon_restart_stale_pid_recovered — the persisted config reconnected successfully.
• daemon_restart_stale_pid_recovery_failed — the relaunch attempt failed; the detail field carries the error.

A cmdline/exec mismatch is not auto-recovered, because a different live process owns that PID and launching over it could be unsafe.

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 = 18200
udp = true
auth = { enabled = true, username = "xrat", password = { env = "XRAT_SOCKS_PASSWORD" } }

HTTP

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

Shadowsocks

[runtime.shadowsocks]
enabled = false
host = "0.0.0.0"
port = 18202
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 = []

Routing

Managed sessions apply [routing.direct] before [routing.block], with the proxy as the default route. Xray/V2Ray supports domain, IP/CIDR, geosite, and GeoIP rules. sing-box supports domain and IP/CIDR rules; xrat reports an error for sing-box geosite/GeoIP entries until rule-set translation is available. Connection-test probes intentionally remain proxy-only.

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"

Hysteria2 (hy2) configs are selected for sing-box automatically, even when engine = "xray", because Xray/V2Ray cannot generate a compatible Hysteria2 runtime config. Non-Hysteria2 configs with engine = "sing-box" fail with an unsupported-combination error until their sing-box runtime generators are added.

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 rotate now 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 reachability of the configured local inbounds
4. Starts an asynchronous HTTP request through the active SOCKS5 or HTTP proxy
5. Applies a current-session result only; stale results from replaced sessions are discarded

Process exit and inbound loss are control-plane failures and trigger recovery immediately. Proxied HTTP failures are data-plane failures and must occur runtime.rotation.health_failure_threshold times consecutively. A successful probe resets the counter. Shadowsocks-only sessions use process and socket checks because the daemon does not embed a Shadowsocks HTTP client.

Failure Handling

When a health failure reaches its trigger condition:

1. Log the failure — Record in daemon logs
2. Update session — Persist a specific reason code and per-config cooldown
3. Trigger rotation — If health_trigger_enabled, start rotation
4. Select safely — Fresh-test enabled candidates outside their cooldown

ProxyStatus reports the configured threshold, consecutive failure count, whether a probe is in flight, last check time/error, and pending recovery state.

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 the process executable and command line match the expected runtime engine and session config?
3. Decision:
   • PID alive + match → reattach (keep as running)
   • PID alive + mismatch → mark failed (different process reused PID)
   • PID dead → mark failed

Reattach Validation

Process identity is queried through sysinfo rather than reading /proc directly, so reattach works on Linux, macOS, and BSD:

#![allow(unused)]
fn main() {
fn validate_reattach(pid: i64, expected_binary: &Path) -> bool {
    let exe = process_exe_path(pid);   // sysinfo Process::exe()
    let cmd = process_cmd_args(pid);   // sysinfo Process::cmd()
    exe_matches(exe, expected_binary) && cmd_contains_session_config(cmd)
}
}

This prevents reattaching to a different process that happens to have the same PID. On OpenBSD exe() may be unavailable; the command-line check still applies.

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 = true
interval_secs = 1800
health_trigger_enabled = true
health_failure_threshold = 3
cooldown_secs = 300
test_concurrency = 0
test_stages = ["icmp", "real_delay"]
refresh_subscriptions = false

Refresh Before Rotation

With refresh_subscriptions = true, automatic (timer/health) rotation first re-fetches every URL-backed subscription using the same import + reconciliation path as a manual refresh: still-present configs are updated, and provider-removed configs are soft-deleted so they are excluded from candidate selection. Non-URL sources are skipped. Refresh failures are recorded as separate subscription/rotation events and never abort rotation — selection proceeds with whatever configs are present, so the old runtime is not left stopped because a provider was unreachable.

This applies to timer- and health-triggered rotation. For a one-off manual rotation, use xrat rotate now --refresh instead (see rotate now).

Rotation Triggers

Timer Trigger

Scheduled rotation every interval_secs:

interval_secs = 1800  # rotate every 30 minutes

The timer runs only while a managed runtime is active. Starting the daemon with no runtime does not select or start a config automatically. A failed timer attempt is rescheduled for the normal interval instead of retrying in a tight loop.

Health Check Trigger

Triggered when the active proxy fails a health check:

health_trigger_enabled = true

The daemon monitors proxy health every 15 seconds. A dead runtime process or an unreachable configured inbound triggers recovery immediately. When an active SOCKS5 or HTTP inbound exists, xrat also sends an asynchronous HTTP request through that proxy using [testing.real_delay] URL, timeout, redirect, and accepted-status settings. These data-plane failures trigger recovery only after health_failure_threshold consecutive failures; a successful probe resets the counter. Results from a session that has already been replaced are discarded.

Shadowsocks-only runtimes use process and inbound-socket checks because xrat does not currently run the HTTP probe through a Shadowsocks client.

Manual Trigger

Triggered by the user via CLI:

xrat rotate now

Unpinned manual rotation bypasses the timer and per-config cooldown, but still runs fresh candidate tests.

Forced Rotation

Rotate to a specific config:

xrat rotate now --config-id 99

Skips candidate selection and candidate health ranking. The target must still be enabled, different from the active config, and pass native engine preflight validation.

Cooldown Protection

After a health failure, the failed config receives a per-config cooldown:

cooldown_secs = 300  # 5 minutes

Automatic timer and health selection excludes configs whose cooldown has not expired. Manual rotation may select them; a pinned manual target explicitly bypasses cooldown.

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 the configured stages freshly on all candidates concurrently. Stored test rows are not reused for rotation:

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

For each candidate, xrat runs the normal test pipeline and records the result. ICMP is diagnostic only. A candidate qualifies by real-delay when that stage ran, otherwise by download, otherwise by TCP. A candidate cannot qualify from ICMP alone.

Step 3: Filter Failures

Exclude configs that do not pass the qualifying stage.

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. Select candidate — Run fresh tests, or validate an explicit config ID
2. Preflight — Run the selected engine’s native config validator
3. Handoff — Stop the old process and start the replacement on the same inbounds
4. Verify — Wait for the replacement inbound to become reachable
5. Commit or roll back — Mark the replacement active, or reconnect the old config
6. Reschedule — Record the result and schedule the normal next interval

Native preflight commands are xray run -test -c, v2ray test -c, and sing-box check -c. Preflight happens before disruption. Because the old and new runtime use the same local ports, the process handoff cannot overlap; if the replacement fails after the old process stops, xrat reconnects the previous config and reports both the replacement and rollback outcome.

Rotation Status

Check rotation status:

xrat rotate 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 rotate 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 rotate enable

Atomically writes runtime.rotation.enabled = true to config.toml, then enables the running daemon scheduler.

Stop Rotation

xrat rotate disable

Atomically writes runtime.rotation.enabled = false to config.toml, then disables the running daemon scheduler. The active proxy session continues.

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 = ["icmp", "real_delay"]

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

The enabled setting survives daemon restarts because rotate enable and rotate disable update config.toml. Runtime counters and scheduling state are in memory, while per-config cooldown/failure metadata and the active runtime session are persisted in the database.

Troubleshooting

Rotation Not Triggering

Symptom: Timer fires but rotation doesn’t happen

Check:

• Is cooldown active? xrat rotate 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 = 18203

Configuration

[server]
enabled = false
host = "127.0.0.1"
port = 18203
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,
    "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,
    "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,
      "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,
  "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,
    "dial_endpoint_ip": "93.184.216.34",
    "dial_endpoint_country": "US",
    "dial_endpoint_asn": "AS15133",
    "dial_endpoint_geoip_source": "dial_dns",
    "dial_endpoint_fronting": null,
    "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