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, and complete Xray JSON profiles, using SQLite or PostgreSQL for catalog metadata.
• 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 supports managed sessions and test probes for every imported protocol. Hy2 configs use Xray or sing-box according to [runtime].engine; V2Ray cannot run them. The xrat parse --engine auto preview selects sing-box for Hy2.

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 Xray/V2Ray or sing-box local proxy runtime 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
• Arch Linux (AUR) — install xrat-bin (prebuilt) or xrat (from source) on Arch Linux
• 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 install.sh for Linux or macOS and install.ps1 for Windows. It downloads the matching release archive, verifies the checksum, installs xrat, and can run first-time setup for you.

For other install paths, see Arch Linux (AUR), 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 choose [runtime].engine = "sing-box":

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, and on 64-bit Windows. 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 support remains experimental. This source branch adds daemon IPC, an optional LocalSystem service with ordinary-user TUI/Web clients, desktop proxy integration, and staged upgrades. Managed Windows TUN and coordinated user/service upgrades are implemented in this branch. Native acceptance is still tracked in the Windows milestone; these source changes do not establish full Windows support. Windows binaries are 64-bit only.

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

Windows installer and release packaging

Windows release builds publish xrat-<tag>-x86_64-pc-windows-msvc.zip and xrat-<tag>-aarch64-pc-windows-msvc.zip, containing xrat.exe, LICENSE, README.md, and an embedded browser bundle. The release workflow reuses the Windows build/test workflow and waits for both targets before publishing; SHASUMS256.txt covers the Windows ZIPs alongside the Unix archives.

Invoke-WebRequest https://raw.githubusercontent.com/mhyrzt/xrat/master/install.ps1 -OutFile install.ps1
.\install.ps1 -Yes

The script verifies SHA-256 before installing to %USERPROFILE%\.local\bin, adds that directory to the user PATH, and delegates configuration and core installation to xrat setup. Restart the terminal to use the updated PATH. Options are -InstallDir <directory>, -Version <tag>, -Yes, -NoSetup, and -FromSource. Source installation requires a repository checkout, Rust with MSVC build tools; it builds browser assets before the binary using a checksum-pinned standalone Tailwind tool. On Windows ARM64, that CSS build tool runs through Windows 11’s x64 emulation; XRAT and proxy cores remain native ARM64. Without a terminal, setup is skipped unless -Yes is provided, matching the shell installer’s unattended behavior. Linux desktop and linger flags do not apply to Windows. Stop XRAT before rerunning the installer. The Windows source branch also contains an experimental staged self-upgrader: stop the daemon, run xrat upgrade, exit the upgrading process when prompted, then run xrat upgrade --status to inspect completion. A staged operation is not yet an installed upgrade. Migration failure retains the new binary and a backup for manual recovery; binary rollback does not undo database migrations. Native acceptance and service-coordinated upgrades remain pending.

PowerShell proxy integration emits a script for the caller’s session:

xrat proxy shell enable --shell powershell | Out-String | Invoke-Expression
xrat proxy shell disable --shell powershell | Out-String | Invoke-Expression

Enable preserves previous proxy variables; disable restores them. NO_PROXY is retained. Setup writes a PowerShell completion script under the user data directory (.local/share/xrat/completions/xrat.ps1 by default); dot-source it in the shell where completions are wanted. Setup does not edit your PowerShell profile. Use xrat tui to launch the terminal interface.

Arch Linux (AUR)

xrat is available in the Arch User Repository (AUR) as both a prebuilt binary package and a source package.

For other install paths, see Installation Script, Cargo Install, Docker Install, or Manual Binary Install.

Packages

Installation

Using an AUR Helper

With yay:

# Prebuilt binary (recommended)
yay -S xrat-bin

# Or build from source:
yay -S xrat

With paru:

# Prebuilt binary (recommended)
paru -S xrat-bin

# Or build from source:
paru -S xrat

Manual Installation (makepkg)

You can clone the repository and build manually without an AUR helper:

# For xrat-bin
git clone https://aur.archlinux.org/xrat-bin.git
cd xrat-bin
makepkg -si

# Or for xrat (from source)
git clone https://aur.archlinux.org/xrat.git
cd xrat
makepkg -si

First-Time Setup

AUR packages install the xrat binary to /usr/bin/xrat alongside system assets (desktop launcher, completions, man pages, service templates).

To initialize the configuration directory, database, and managed proxy cores, run setup:

xrat setup

Setup is idempotent and re-runnable. Use -y to accept defaults non-interactively, or xrat setup --check to verify your environment without making changes.

Then follow the Quickstart to import configs and connect.

Update and Uninstall

Update

Using your AUR helper:

yay -Syu
# or
paru -Syu

Uninstall

Remove the package and unused dependencies:

sudo pacman -Rns xrat-bin
# or
sudo pacman -Rns xrat

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 compiles xrat from this checkout. Tagged releases use the Linux musl binaries built by the release workflow for their amd64 and arm64 images, so the Docker job does not compile xrat again. Both paths include Xray-core and sing-box in the final image.

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

Development builds use opt-level = 0 and retain Cargo’s default debugging information and incremental compilation. Release builds use opt-level = 3, Thin LTO, and symbol stripping. These release settings also apply to the GitHub release workflow and source-built Docker images. Thin LTO can increase build time; symbol stripping reduces diagnostic information in distributed binaries.

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 local version, formatting, lint, and workspace-test gates:

just ci

That expands to:

just version-check
just fmt-rust-check
just lint
just test

GitHub CI additionally validates public SDK features and pinned native engines, and checks the workspace on macOS for both x86_64-apple-darwin and aarch64-apple-darwin. The macOS jobs run cargo check --locked --workspace with the corresponding --target on macOS runners, catching platform-specific compile errors before release packaging.

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, or complete Xray JSON profile. SIP008 JSON subscriptions are not currently supported by import. Complete Xray profiles preserve their own DNS, routing and inbounds; see importing for compatibility restrictions.

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
restore_connection_on_start = false

[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 supports domain rules, IP/CIDR rules, and geosite/geoip entries through remote SagerNet rule-sets cached under the runtime directory; Xray’s local .dat assets are not reused.

Managed sing-box sessions and sing-box probes require a sing-box >=1.13.0 binary. Newer versions are accepted; conformance fixtures cover >=1.13.0, <1.15.0 and versions outside that range log a warning. xrat setup installs the pinned v1.13.21 release. See the sing-box compatibility contract.

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. This step is skipped on Windows, where the shortcut would need a .cmd wrapper; start the TUI with xrat tui instead.
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.

Managed sing-box is installed at the pinned conformance release v1.13.21. The runtime accepts any sing-box >=1.13.0, so a newer user-supplied binary works without setup; pre-1.13 binaries are rejected before launch and versions outside the planned >=1.13.0, <1.15.0 conformance range log a warning. See the sing-box compatibility contract for the full contract.

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

install

Install a managed proxy core directly from its upstream GitHub releases.

xrat install <CORE> [--version <VERSION> | --prerelease]

Supported cores are xray, v2ray, and sing-box (singbox is also accepted). Without --version, XRAT installs the latest stable release reported by GitHub. Pass --prerelease to install the newest published prerelease instead.

# Install the latest Xray release
xrat install xray

# Install a specific V2Ray release
xrat install v2ray --version 5.52.0

# A leading v in the version is accepted
xrat install sing-box --version v1.13.2

# Install the newest published Xray prerelease
xrat install xray --prerelease

XRAT downloads the platform-specific asset from the core’s official repository, verifies its published SHA-256 digest, stages and validates the binary, and then atomically installs it under the user data directory. It also updates the matching runtime binary path in config.toml and creates a command link in ~/.local/bin when that location is available. Existing non-XRAT command links are left untouched.

The download is streamed with a progress bar in interactive terminals. Completion output reports the installed core, version, binary path, and updated config.toml path. The same details are recorded as a best-effort core_installed event for xrat logs.

Managed installation currently supports Linux and macOS on x86-64 and ARM64, and Windows on x86-64 and ARM64.

import

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

xrat import <input> [--name <name>] [--header 'Name: value']...

Arguments

Options

Input Formats

xrat automatically detects the input format:

Complete Xray JSON is imported from a local file or pasted JSON object with an outbounds array as one profile, preserving the original file rather than extracting individual nodes. SIP008 JSON subscriptions remain unsupported. URL-backed JSON profiles and automatic refresh are unsupported; download the file and import it locally. Browser uploads and machine-gateway imports cannot provision arbitrary engine configuration; use the local CLI/TUI.

xrat import ./xray-conn-london.json --name london-vpn
xrat list
xrat connect <config-ref>
xrat show config <config-ref> --raw > restored.json

The --raw output contains credentials and is byte-for-byte identical to the imported JSON. The original input file can be moved or deleted after import. See Xray JSON profiles for runtime and backup requirements.

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 with custom headers:

xrat import https://example.com/sub.txt \
  --header 'X-HWID: device-id' \
  --header 'User-Agent: Happ'

Headers are saved for update and automatic refreshes. Each successful import replaces the saved set; omitting --header clears it. With headers, redirects must keep the same scheme, host, and port. Header values are stored unencrypted.

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

For a new URL subscription without --name, the name comes from Profile-Title (plain text or base64:), then the Content-Disposition filename, then the URL fragment, then a name, title, tag, or remark query parameter. An explicit name always wins, including names beginning with sub-.

Reimporting or refreshing a saved subscription without an explicit name preserves its existing name. The TUI and Web UI follow the same rules. In the TUI, accepting the suggested name leaves automatic detection enabled; typing a name makes it explicit. The generated TUI suggestion is used when no metadata supplies a name.

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.

Subscription URL lists

Normal imports decode and parse subscription contents as proxy nodes. HTTP(S) links inside a response or local node file are never fetched as subscriptions. To import a list of subscription URLs, put one URL per line in a local file:

xrat import ./subscriptions.txt --url-list --name "Combined subscriptions"

Blank lines and lines starting with # are ignored. Every remaining line must be an HTTP(S) URL. Each URL is fetched once; its response is parsed as nodes without following embedded URLs. The results are merged under the local file source, which is not automatically refreshed. Re-run the command to refresh it. --url-list requires a local file and cannot be combined with --header.

Previously, imports automatically fetched HTTP(S) lines inside their contents. Use --url-list for files that intentionally contain subscription URLs. For a single HTTP(S) proxy URI supplied directly, use xrat add "https://host:443".

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

Failure diagnostics

Updates retain per-subscription success/failure counts. Failures distinguish request timeouts, DNS lookup or connection failures, TLS verification, redirect limits, unreadable responses, and HTTP status codes such as 401, 404, 429 or 503. Unknown transport failures remain explicitly unknown.

Subscription error messages omit URLs, credentials, path/query tokens, redirect targets and response bodies. Status descriptions come from the standard HTTP status code rather than an untrusted server response. These diagnostics are shared by CLI and TUI updates.

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

Windows machine profile

On the registered operator’s ordinary terminal:

xrat --profile machine test --enabled-only --format json --output results.json
xrat --profile machine test <config-ref>
xrat --profile machine test --latest-run-summary

Machine probes run as service jobs using administrator-configured cores, target URLs, timeouts, concurrency, and enabled stages. CLI skip flags and bulk selection filters still apply; URL, timeout, and concurrency overrides are rejected. A job accepts at most 10000 distinct config IDs. Ctrl+C requests cancellation and waits for a terminal service response; an unconfirmed cancellation reports an error.

The service retains the latest job’s completed result rows until another job starts, including completed rows from a cancelled job. If it is replaced before the CLI finishes reading it, the command reports an error instead of writing partial results. The latest persisted run can still be summarized with --latest-run-summary. Single-config and bulk output use the existing presenters and formats. These commands never bootstrap a user catalog or run a local test as fallback. Machine --ping is explicitly unsupported; continuous ping remains available in the separate user profile.

Native Windows engine and console cancellation acceptance remain pending.

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 the configured engine. Hysteria2 (hy2) runs through native Xray when [runtime].engine = "xray", or sing-box when the engine is sing-box; V2Ray rejects it. Xray rejects Hy2 URI options it cannot represent before launch. 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 by this command.

XRAT automatically removes managed stdout/stderr logs for completed sessions older than the 10 newest completed sessions. Cleanup runs at application startup and before connections and runtime replacements. It covers both Xray/V2Ray and sing-box session logs in the runtime directory, including files accumulated before upgrading. Starting, running, and stopping sessions are protected. Cleanup failures produce warnings without blocking normal operations.

This retention policy does not cap the size of an active log, rotate daemon.log, or remove generated JSON configs, custom engine logs, or files whose sessions are absent from the database.

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 crates/xrat-app/templates/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 (crates/xrat-app/templates/launchd/, crates/xrat-app/templates/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.

Windows machine service

Windows service installation requires an elevated terminal:

xrat daemon install --dry-run --start
xrat daemon install --start

The service runs as LocalSystem from a protected Program Files directory and stores its configuration, SQLite catalog, runtime files, and engine binaries under the ProgramData known folder, in XRAT-Service. The installing user is registered as its operator. When elevating with a different administrator account, pass --operator-sid <SID> for the intended operator.

Provision service cores explicitly from an elevated terminal while the machine service is stopped. Core installation uses official release metadata/checksums, checks the staged executable version, and writes only the fixed protected core path. It leaves the service stopped and does not edit user configuration or PATH.

xrat --profile machine daemon stop
xrat --profile machine install xray --version 26.9.30
xrat --profile machine install sing-box --version 1.13.21
xrat --profile machine daemon start

An exclusive profile lease prevents core provisioning while a service host is active, and prevents service startup during provisioning. Locked executable or activation errors preserve the previous core. Routine gateway requests cannot install cores.

The registered operator can use these commands from an ordinary terminal:

xrat --profile machine daemon status
xrat --profile machine daemon start
xrat --profile machine import https://example.com/subscription
xrat --profile machine list configs
xrat --profile machine connect <config-ref>
xrat --profile machine status --json
xrat --profile machine disconnect
xrat --profile machine daemon stop

--profile user is the default. Machine commands use the service gateway and never open a user catalog or fall back when the service is unavailable. Path and database overrides are rejected. Supported catalog commands currently include add, import, update, list, show, enable, disable, delete, restore, purge, and test. Machine rotate enable/disable/status/now also use the supervisor; rotation controls are volatile and do not edit administrator policy. rotate now --refresh refreshes subscriptions through the ordinary client. Machine logs reads service events and fixed daemon/engine feeds, including --follow, event --level/--format, and logs clear --yes. Machine log requests accept --lines 1..2000; file reads are bounded to 512 KiB per request and report omitted older content. The operator never opens protected log files directly. Machine frontends run from an ordinary terminal:

xrat --profile machine tui
xrat --profile machine serve
xrat --profile machine webui --no-open

These frontends require a ready service and reject elevated tokens. Their configuration and SQLite UI/authentication store live in machine-client under the user data root. They read and modify the service catalog through the gateway; that local store never substitutes for an unavailable service. Configure Web credentials in the frontend configuration before enabling its Web interface. HTTP authentication, roles, and CSRF checks still apply. Machine legacy exports (/json, /configs, and key-based /b64) require a configured server.key; absence of a key does not enable anonymous machine exports. Account-token subscription access retains its existing scope and revocation checks.

Test jobs use administrator-configured service targets, timeouts, concurrency, and cores. Machine CLI test supports single references, bulk enabled/active/ subscription filters, existing output formats, and --latest-run-summary; Ctrl+C requests cancellation and waits for the service result. Policy overrides and machine test --ping are explicitly unsupported. TUI split-policy edits and Web core/GeoIP maintenance, policy validation, and upgrades require local administrator maintenance. Frontend server settings and TUI preferences remain editable. Machine proxy reads service-owned endpoints/PAC while applying shell and desktop changes in the interactive user’s session. Desktop disable/status and shell restoration remain available without a running service and do not open a catalog/UI database. PAC policy, runtime state, probe history, and operational logs come from the service; API request logs stay in the frontend store with a separate display cursor.

Add --with-api during elevated installation to register the optional XRAT-Machine-API login task. It uses the registered operator’s existing interactive token with least privilege, stores no password, and launches the protected executable as --profile machine serve --host 127.0.0.1. It starts at the operator’s next logon. --start starts the SCM service immediately; an already logged-on operator can start the API task from Task Scheduler without elevation. Configure server.key and optional Web credentials in that user’s machine-client configuration first.

The task grants the operator read/run access; administrators control its registration and action. Reinstallation preserves operator identity. Uninstall removes the owned task and service while preserving protected data and user UI/authentication data. Unexpected task ownership, permissions, or actions cause an explicit error rather than replacing or deleting another task. Native task registration, login, and ACL acceptance remain pending.

Driver provisioning and coordinated service upgrade are still under implementation. Windows daemon install --tun returns an explicit unsupported operation error.

Import files and subscription URLs are read by the invoking user. The service receives bounded link bodies and source metadata, then uses the shared parsing and catalog lifecycle services. Root engine JSON and structured engine extension parameters require administrator provisioning; the gateway rejects them. Routine requests cannot supply executable paths, SQL, service configuration, or driver sources. Listing pagination preserves shared filters and ordering, and exports include the complete filtered selection.

After service startup, crash recovery, or restart, the service reconciles and cleans stale runtime ownership and remains disconnected with rotation disabled. Connect explicitly to resume. Uninstall requires elevation and preserves the protected profile and installed executable. Source and local tests do not yet establish native Windows runtime acceptance.

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

Windows machine runtime

Use an ordinary operator terminal to read service-owned endpoints and policy:

xrat --profile machine proxy info
xrat --profile machine proxy pac print
xrat --profile machine proxy shell enable --shell powershell | Out-String | Invoke-Expression
xrat --profile machine proxy desktop enable

The service supplies runtime endpoints and PAC routing policy. PAC URL settings come from the operator’s machine-client/config.toml; enable [server] and pac_enabled when using PAC, and configure the frontend’s HTTP/HTTPS origin and PAC host allowlist appropriately. Missing frontend preferences use defaults; invalid preferences report an error. Proxy commands do not initialize a catalog or a UI database.

Desktop settings and their recovery record belong to the interactive user. They never change LocalSystem’s HKCU. Recover after the service stops or is removed with:

xrat --profile machine proxy desktop disable
xrat --profile machine proxy shell disable --shell powershell | Out-String | Invoke-Expression

Desktop status/disable and shell restoration do not require the service or a catalog database. Shell output must be applied in the current shell; emitting a script cannot change the parent process by itself. Owned desktop restoration continues to preserve changes made by another application.

IPv6 wildcard endpoints use loopback for connection URLs, with bracketed IPv6 literals and URI-escaped scope IDs. Native Windows desktop/Terminal acceptance remains pending.

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.

Runtime and TUN indicators refresh in the background, including changes made by the CLI or daemon. A failed poll is retried on the next polling cycle.

On Unix terminals that report Kitty base-layout keys, command shortcuts follow physical US QWERTY positions across keyboard layouts, including shifted commands such as U, K, and ?. Text fields preserve the characters you type. Other terminals use their normal character bindings; standalone Escape and ordinary text input remain available.

Release notes after upgrading

After a successful release upgrade, xrat caches the installed release’s notes in release-notes.json under the xrat data directory (XRAT_PATH, or ~/.config/xrat). Notes appear only in a “What’s new” modal on the next TUI launch of that version, with Markdown formatting and wrapped, scrollable text. No release notes are printed by the upgrade command.

Use ↑/↓ or j/k to scroll, PageUp/PageDown to move a page, and Home/End to jump to the start/end. Press Enter or Esc to dismiss and save that version as seen. Closing the terminal before dismissal leaves the notes pending for the next launch. Reinstalling the same version preserves dismissal.

Viewing works offline. If release notes cannot be fetched, the modal shows a link to the release instead. A notes fetch or cache failure does not fail the upgrade. Source upgrades do not fetch GitHub release notes.

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.

Mouse control is supported out of the box: click any card to focus it, click a row in the table to select it, click tabs to switch views, and scroll the mouse wheel to navigate (1 row at a time in tables, 2 lines in text cards). Hover-based scrolling works across all cards without needing to click first. Mouse support can be toggled in the Settings modal or via mouse = false under [tui] in config.toml.

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, parser mode, and the TUI color theme. 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. Theme changes preview live immediately as you cycle options. The selector includes built-in palettes and custom names defined under [tui.themes.<name>]. Define custom colors in TOML; the Settings modal selects palettes rather than editing individual colors. Reset previews default, and discarding changes restores the last saved palette. See custom theme configuration for color fields and examples.

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.

tun

Apply managed TUN capture to the current connection and inspect its readiness.

xrat tun <subcommand>

TUN capture creates a network interface and system routes, so the engine binary needs CAP_NET_ADMIN. On Linux this is a file capability, granted with setcap. See TUN Capture for the full workflow and caveats.

enable / disable

Enable TUN on the current connected config, or return it to local proxy mode:

xrat tun enable
xrat tun enable --kill-switch
xrat tun disable
xrat tun enable --json

The runtime owner checks engine support, capabilities, interface ownership, and native config validity before stopping the current session. It reconnects the same config in the requested mode and saves runtime.tun.enabled only after a successful change. Startup or save failures attempt to restore the previous mode and connection. Repeating a command does not restart an already matching session. When disconnected, the setting is saved for the next connect.

Normal toggles do not require setup or daemon restarts. First-time privileges, replacement binaries, or upgrading a daemon from a version without live toggles may require setup and one restart; the error explains the next step. A CLI command never takes over a standalone TUI’s running session: press U in that TUI instead. A global --config override must match the daemon’s config file.

In the TUI, press U for the same checked live toggle. Its result appears in the status message and log. You can also change only runtime.tun.enabled in settings and save with Ctrl+S to apply immediately. Save other settings separately when changing the enabled flag; their existing restart workflow still applies.

status

Report TUN readiness for the current configuration:

xrat tun status

TUN status
engine                xray 26.7.11
active capture        yes
active config         a1b2c3
active interface      xrat0
engine check          ready
configured TUN        yes
configured interface  xrat0
systemd service       ready (NoNewPrivileges=false override present)
engine file           /home/user/.local/share/xrat/cores/xray/xray  ready (cap_net_admin,cap_net_raw=ep)
xrat file             /usr/local/bin/xrat  ready (cap_net_admin,cap_net_raw=ep)

--json prints the same data as structured JSON. tun_enabled is the saved setting; tun_active requires a running session and an owned kernel TUN device with a matching interface index. It does not prove external traffic or DNS reachability. ready covers engine support and privilege checks; it is separate from active capture.

setup

Grant CAP_NET_ADMIN and CAP_NET_RAW to the files TUN needs and configure systemd service permissions:

xrat tun setup

On Linux the selected engine receives cap_net_admin,cap_net_raw,cap_dac_read_search,cap_sys_ptrace+ep for capture and process matching. XRAT receives only cap_net_admin,cap_net_raw+ep for cleanup. On Linux systems with an installed systemd user service, it also automatically installs a drop-in override ~/.config/systemd/user/xrat-daemon.service.d/10-tun.conf (NoNewPrivileges=false) and reloads the user daemon (systemctl --user daemon-reload). Use --dry-run to print the commands and planned file changes without running them.

Restart an installed systemd daemon with systemctl --user restart xrat-daemon.service so it picks up the override and capabilities. For a standalone daemon, use xrat daemon restart.

Capability restoration uses normal sudo authentication and may prompt for a password. XRAT does not install passwordless sudoers rules. If you previously used the removed --sudoers helper, review and remove /etc/sudoers.d/xrat-tun with sudo rm /etc/sudoers.d/xrat-tun to revoke its persistent grant.

File capabilities are automatically restored during xrat upgrade (and core reinstalls via xrat install) when TUN was previously configured (see auto_setup_on_upgrade in settings), so manual re-setup is only required if auto-restoration is disabled or failed.

Requirements

• Linux: Xray >= 26.7.11 or sing-box, with libcap tools (setcap/getcap).
• macOS: sing-box, a root runtime owner and a numbered utun interface.
• Windows: protected LocalSystem machine service; Xray >= 26.9.30 and < 27.0.0, or sing-box >= 1.13.21 and < 1.14.0.
• V2Ray TUN is unsupported.

Windows preparation

In an elevated administrator shell, install the machine service, stop it, then prepare the protected driver files:

xrat --profile machine daemon stop
xrat --profile machine tun setup --dry-run
xrat --profile machine tun setup

Setup downloads the official Wintun 0.14.1 archive over HTTPS. It verifies pinned SHA-256 hashes for the archive, the native x64 or ARM64 DLL, and the license. Windows Authenticode verification checks the staged DLL against the local trust policy without network retrieval or a fresh revocation check. Files are staged with administrator ownership in the protected machine core directory and activated beside xray.exe; the original license is retained as wintun-LICENSE.txt. Repeating setup with verified files performs no download. The service must be stopped and remains stopped. Setup does not create a network adapter, change routes or DNS, or enable capture.

Windows capture runs only in the protected machine service. Configure its protected engine and TUN addresses as administrator, then start the service and use the ordinary registered operator account:

xrat --profile machine daemon start
xrat --profile machine tun enable --json
xrat --profile machine tun status --json
xrat --profile machine tun disable

For sing-box automatic routing, set runtime.tun.strict_route = true before enabling capture. Split policy changes require administrator maintenance; ordinary machine CLI toggles cannot change that policy. User-profile capture is rejected. Routine toggles do not download drivers or change driver policy.

Startup verifies the Wintun device identity, configured interface addresses, per-interface DNS, and capture-route coverage before reporting active capture. Conflicting foreign VPN routes or overlapping addresses preserve the current connection. Cleanup waits for the engine-owned adapter and routes to disappear; it retains the ownership journal on failure and never deletes unrelated adapters or rewrites physical-interface DNS. Service crash containment terminates child engines; service startup reconciles stale ownership and remains disconnected until explicitly requested.

These Windows paths are implemented, but native x64/ARM64 traffic, DNS, replacement, crash and reboot acceptance remains pending. Driver preparation or local compilation alone does not establish full Windows support.

When a daemon is running, tun status also inspects its effective CAP_NET_ADMIN and NoNewPrivs through the daemon socket peer PID. The JSON daemon object contains its PID, readiness and status; it is null when no daemon is reachable. A drop-in on disk alone does not make an already-running daemon ready.

Split tunneling

whitelist sends selected applications through the proxy and others direct. blacklist sends selected applications direct and others through the proxy. all captures all applications. DNS interception and private/LAN routing retain their precedence. Names, executable paths and application directories match as alternatives.

Desktop selections preserve their desktop ID, real executable and companion workers. Executable symlinks include their canonical targets. Shell wrappers are inspected for literal exec /path/to/app statements and are never executed. Variable-based wrappers require an explicit executable or application directory. Inspect resolved rules and warnings with xrat tun split list before relying on application matching. xrat tun split status also shows wrapper warnings and the compiled engine matchers.

Kill Switch

The TUN kill switch provides fail-closed isolation for mode all: no packets leave the host via physical network interfaces using the real IP address if the proxy engine crashes, stops unexpectedly, or drops the connection.

Important: The kill switch requires split_mode = "all". Split tunneling (whitelist or blacklist) deliberately allows traffic to bypass the tunnel directly and is rejected when the kill switch is enabled.

# Check current kill switch status
xrat tun killswitch status

# Enable kill switch (auto mode)
xrat tun killswitch on

# Disable kill switch
xrat tun killswitch off

# Emergency reset (flushes firewall tables and resets state)
xrat tun killswitch reset

The firewall backend defaults to Linux nftables (table inet xrat_killswitch) with automatic fallback to iptables / ip6tables (XRAT_KILLSWITCH chain). Rules isolate egress so that only traffic over loopback (lo), the TUN interface (xrat0), packets marked with the engine socket mark (0x162), proxy endpoint destinations, and DHCP/ND/LAN subnets (when allow_lan = true) are accepted; all other egress packets are dropped.

Modes:

• off: No kill switch firewall rules are loaded.
• auto: Firewall rules are engaged when TUN session starts and disengaged on explicit disconnect or tun disable. On engine crash or unexpected termination, the fail-closed rules remain active.
• strict: Firewall rules remain engaged even after manual disconnect until explicitly turned off or reset.

macOS

Set runtime.engine = "sing-box". Managed capture defaults to utun99 and requires a root runtime owner with explicit config and database paths:

sudo xrat --config /absolute/config.toml --database /absolute/db.sqlite daemon start

xrat tun setup prints instructions; it does not install a root launchd service. The installed user launchd service cannot acquire root privileges. Explicit paths ensure the privileged process uses your configuration.

Application discovery searches /Applications, /System/Applications and ~/Applications. A bundle directory such as /Applications/Firefox.app/ includes nested helper processes. Running apps use executable paths or their enclosing bundle directories.

strict_route and route_exclude_address are rejected on macOS. Startup refuses VPN default routes or conflicting capture routes. Cleanup waits for the engine to release its utun socket, retaining ownership if release fails. macOS traffic, DNS and restoration acceptance requires a native privileged run; Linux checks do not establish that runtime proof.

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]

On Unix, the new binary is staged beside the current executable and atomically renamed over it. On Windows, a verified helper applies the staged transaction after the upgrading process exits; inspect xrat upgrade --status afterward. Upgrade discovery runs before database initialization, allowing recovery from a database migration or connection failure. Completion requires migrations using the updated binary.

Release notes after upgrading

After a successful release upgrade, xrat caches the installed release’s notes in release-notes.json under the xrat data directory (XRAT_PATH, or ~/.config/xrat). Notes appear only in a “What’s new” modal on the next TUI launch of that version, with Markdown formatting and wrapped, scrollable text. No release notes are printed by the upgrade command.

Use ↑/↓ or j/k to scroll, PageUp/PageDown to move a page, and Home/End to jump to the start/end. Press Enter or Esc to dismiss and save that version as seen. Closing the terminal before dismissal leaves the notes pending for the next launch. Reinstalling the same version preserves dismissal.

Viewing works offline. If release notes cannot be fetched, the modal shows a link to the release instead. A notes fetch or cache failure does not fail the upgrade. Source upgrades do not fetch GitHub release notes.

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.
5. If TUN was previously configured (or when --tun-setup is passed), automatically restores TUN file capabilities via tun setup. If a running daemon is detected, restarts it so the process picks up the newly granted capabilities (configurable via [runtime.tun].auto_setup_on_upgrade and [runtime.tun].restart_daemon_on_upgrade).

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

xrat upgrade --version v0.2.1 --force

If GitHub requests fail, check connectivity to both api.github.com (release lookup) and github.com (archives and checksums). You can use a working local SOCKS proxy; replace the example port with your proxy’s port:

ALL_PROXY=socks5h://127.0.0.1:1080 xrat upgrade

--version skips release lookup but still requires archive downloads. A local source build below avoids GitHub release requests; Cargo may still need network access for missing dependencies.

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.

Windows coordination

Run user-profile upgrades from an ordinary shell. The helper shuts down the user daemon and managed connection, replaces the executable, applies user migrations, and restarts a previously active daemon when permitted by --no-restart-daemon and runtime.tun.restart_daemon_on_upgrade.

For the protected machine installation, use an elevated administrator shell:

xrat --profile machine upgrade
xrat --profile machine upgrade --status

Machine downloads and helper files remain in administrator-owned staging. Before replacement, the helper validates and pauses the optional ordinary-user API task and stops the SCM service. It applies protected database migrations by starting the updated service as SYSTEM. A previously stopped service is stopped again after migration; restart suppression also leaves it stopped. The API task’s enabled state is retained, and its prior running state is restored when restart is allowed. The task remains an ordinary interactive-user process.

Failure before replacement preserves the original binary and attempts to restore prior service/task state. After migrations may have run, failure retains the new binary, backup and transaction for explicit recovery; it does not roll back the database. Inspect status and restore service/task state after resolving the reported error. A retained staged/applying transaction blocks another upgrade until reviewed. Linux --tun-setup flags are rejected; Windows driver setup is explicit. Machine upgrades do not write an administrator’s release-notes cache.

Native Windows service, task and migration recovery acceptance remains pending.

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 Xray or 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 — managed runtime sessions and test probes for imported protocols

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

The parser recognizes Shadowsocks SIP008 format, but JSON input is not currently accepted by import:

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

Xray JSON

Import a complete Xray configuration as one native profile:

xrat import ./xray.json --name london-vpn
xrat connect <config-ref>
xrat show config <config-ref> --raw > restored.json

XRAT keeps a private copy of the original bytes, including custom XHTTP fields such as extra.xmux, DNS, routing, multiple outbounds and unknown fields. It does not normalize or inject settings into this JSON. Xray performs native validation before an existing connection is stopped. Import checks JSON syntax and shape; successful import alone does not prove the configuration is accepted by Xray.

Profiles use xray-json as their catalog type and have no single proxy endpoint. They support the existing references, names, enable/disable, soft delete/restore, CLI/TUI/daemon connection lifecycle and individual raw export. The TUI import dialog accepts a local file path or pasted JSON. A repeat import of identical bytes reuses the reference and restores a soft-deleted profile; changed bytes create a separate profile. Node probing, automatic rotation and share-link subscriptions are unsupported. Export a profile individually instead of joining its JSON with other records.

Runtime requirements:

• Select runtime.engine = "xray" and disable XRAT-managed TUN and kill switch. The daemon pauses automatic rotation while a raw profile is active and reports rotation_paused_for_xray_profile; reconnect a node and enable rotation to resume it. Raw TUN inbounds are rejected because their capture ownership cannot be verified.
• Include a local TCP SOCKS or HTTP inbound with a single nonzero port for startup readiness. Multiple inbounds are preserved; XRAT reports the first supported local endpoint of each type. It does not add an inbound when none is suitable.
• The profile owns its DNS, routing, TLS, authentication, logging and transport behavior. XRAT’s generated-runtime settings do not override them. XRAT traffic statistics and automatic health probing are unavailable for raw profiles.
• Relative paths in the JSON retain Xray’s process-working-directory semantics; use absolute paths for referenced certificates, keys and other files.

Local provisioning is required: browser uploads and machine-gateway imports cannot introduce arbitrary engine configuration. Authorized browser users can operate already provisioned profiles and retrieve their original JSON through the existing protected raw-config endpoint. Profiles are limited to 4 MiB.

The complete JSON document is stored in the selected database, so the regular SQLite backup or PostgreSQL dump includes profiles. The database and its backups contain the profile credentials; protect them accordingly. The original import file can be moved or deleted. Profiles imported by the earlier file-backed build are copied into the database the first time XRAT loads or exports them; keep the old profiles/ directory until each such profile has been used once or reimported. Disconnect a running profile before permanently deleting it.

If native validation fails, run xray run -test -c ./xray.json locally for full diagnostics. XRAT keeps raw validation diagnostics out of general event messages because they may contain credentials. Startup diagnostics are in the private session error log.

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 a non-empty payload are automatically purged, including older obsolete rows for that subscription and their test/runtime history. Configs still active or referenced by a starting, running, or stopping runtime session are retained as deleted until a later refresh can safely purge them. Other subscriptions are unaffected. Import and cleanup run in one transaction; a failed config import or empty payload removes nothing. A provider re-add creates a new config row after the previous row has been purged. 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

Subscription URL lists

Normal imports decode and parse subscription contents as proxy nodes. HTTP(S) links inside a response or local node file are never fetched as subscriptions. To import a list of subscription URLs, put one URL per line in a local file:

xrat import ./subscriptions.txt --url-list --name "Combined subscriptions"

Blank lines and lines starting with # are ignored. Every remaining line must be an HTTP(S) URL. Each URL is fetched once; its response is parsed as nodes without following embedded URLs. The results are merged under the local file source, which is not automatically refreshed. Re-run the command to refresh it. --url-list requires a local file and cannot be combined with --header.

Previously, imports automatically fetched HTTP(S) lines inside their contents. Use --url-list for files that intentionally contain subscription URLs. For a single HTTP(S) proxy URI supplied directly, use xrat add "https://host:443".

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:

Native sing-box conformance (contributors)

Run the generated configuration matrix with the checksum-pinned validator:

just runtime-engines /tmp/xrat-engines
just singbox-conformance /tmp/xrat-engines/sing-box /tmp/xrat-conformance

The matrix uses the same sing-box check -c command builder as managed runtime preflight. It covers probe and managed configurations for all seven supported protocols, TLS/REALITY, transports, Shadowsocks methods, Hysteria2 obfuscation, all 16 combinations of SOCKS/HTTP/Shadowsocks/TUN inbounds, TUN stacks, direct and block routing, remote rule sets, Clash API, and cache files. Application DNS fixtures cover UDP, TCP, TLS, QUIC, HTTPS, HTTP/3, local resolution, hosts, policy rules, listener routing, and FakeIP, with and without TUN.

Ordinary Cargo tests report native conformance as ignored (skipped), while checking deterministic fixture generation. Explicit native runs fail if the validator is missing or unusable. CI requires native validation against v1.13.21 and retains each fixture’s emitted JSON and result receipts, including stdout/stderr. A rejection identifies the fixture and prints its JSON. Fixtures target the planned >=1.13.0,<1.15.0 conformance range; a passing run establishes compatibility only with the binary version used for that run. Native syntax checks do not establish connectivity or TUN capture; those have separate network acceptance tests.

QUIC transport requires TLS, and VMess aes-128-ctr is rejected during generation because the supported native validator does not accept it. Shadowsocks inbounds accept AEAD/2022 methods and none; legacy stream ciphers remain available for outbounds but are rejected for inbounds.

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.

Restore after a graceful daemon shutdown

Set runtime.restore_connection_on_start = true to reconnect the last managed profile when the daemon starts after a graceful shutdown. The saved runtime.tun.enabled setting selects the same TUN or local-proxy mode used by the connection. A manual xrat disconnect clears the restore intent. Startup retries failed connections with increasing delays while the daemon remains running, so a network that becomes available after boot can still connect.

This works in the background daemon, including a lingering user service; the TUI and a graphical login are not required. The option defaults to false.

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"

Every protocol has a managed sing-box generator. sing-box sessions and xrat test --engine sing-box require a sing-box >=1.13.0 binary; newer versions are accepted and the pinned conformance target is v1.13.21. Link parameters that cannot be represented exactly, unsupported ciphers/transports, and a non-loopback stats controller are rejected before launch. Xray generation still rejects unsupported Hy2 URI options, and V2Ray rejects Hysteria2.

TUN Capture

Xray and sing-box can capture system-wide traffic through a TUN interface so applications that ignore proxy settings still egress through the active config:

[runtime]
engine = "xray"  # "xray" | "sing-box"; V2Ray rejects TUN

[runtime.tun]
enabled = true
interface_name = "xrat0"
auto_route = true

TUN capture needs elevated network privileges. Grant CAP_NET_ADMIN (and CAP_NET_RAW) to the managed binary of the selected engine:

xrat tun setup

The systemd user unit installed by xrat daemon install keeps NoNewPrivileges=true by default to maintain standard proxy process hardening. When TUN is enabled, running xrat tun setup or xrat daemon install --tun installs a supported drop-in override ~/.config/systemd/user/xrat-daemon.service.d/10-tun.conf with NoNewPrivileges=false and reloads systemctl --user daemon-reload. Effective daemon and service readiness can be verified with xrat tun status. File capabilities are lost whenever the managed core is reinstalled or upgraded.

At least one local inbound (SOCKS by default) must stay enabled. Xray emits a native protocol: "tun" inbound and manages routes with autoSystemRoutingTable; this needs a core with working Linux TUN support (Xray >= 26.7.11), and older cores are rejected before launch. Generated Xray routes match the address families specified in [runtime.tun].address (two /1 prefixes per family, or dual-stack). These routes beat a physical default route even at metric zero without replacing it. Routes are omitted entirely if auto_route = false. sing-box emits type: "tun" with route.auto_detect_interface and routes private/LAN destinations direct. V2Ray reports an unsupported error. Stack selection, strict_route and route exclusions are sing-box-only; Xray rejects non-default requests for these settings. Xray always uses its native stack. See the managed capture contract and DNS policies for version limits and verification commands.

Lifecycle and Interface Safety

macOS managed capture uses sing-box, a root runtime owner and a numbered utun interface. Xray managed TUN remains Linux-only. The kernel releases utun when the engine closes its socket; XRAT verifies release and retains ownership on failure. Route preflight refuses VPN default routes and capture conflicts. See tun on macOS for setup and initial limitations.

Engine capabilities and native preflight syntax validation (xray run -test / sing-box check) are verified before disconnecting or stopping any active session. If preflight or capability checks fail, the current healthy session continues running. Preflight runs before the server’s runtime start and does not create the TUN interface.

Leftover TUN interfaces are cleaned up safely prior to starting the engine. xrat tracks interface ownership in tun-ownership.json and verifies kernel sysfs device metadata (IFF_TUN) before deleting any interface via in-process Linux netlink (RTM_DELLINK). Foreign interfaces, non-TUN devices, missing verified interface indices, or interface index mismatches are strictly rejected. A pending startup record without an index does not authorize cleanup. Ownership records remain available through process teardown and are cleared once the interface is gone or verified cleanup succeeds. Ownership checks and native validation run before replacing an active runtime; cleanup and startup failures during handoff attempt to restore its previous config. If safe cleanup or restoration is impossible, the command reports the rollback failure and preserves unverified interfaces for manual inspection.

DNS

In TUN mode, Xray intercepts DNS traffic (diverting destination port 53 traffic from tun-in to a dedicated dns-out outbound), routing DNS queries through configured DoH servers (defaulting to Cloudflare and Google over IP). To break bootstrapping routing loops before the tunnel starts, node endpoints and DNS provider hosts are pre-resolved into static hosts entries. Private and local network ranges (RFC 1918 / RFC 4193) are automatically routed direct to keep local resources accessible.

Related

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

DNS policies and FakeIP

Managed DNS is opt-in. XRAT does not change /etc/resolv.conf, system resolver settings or firewall rules outside the managed TUN lifecycle. Existing proxy-only configurations keep their current behavior.

Named resolvers

Use named resolvers to distinguish direct, proxied and bootstrap DNS traffic:

[dns]
query_strategy = "UseIP"
use_system_hosts = true
bootstrap_resolver = "bootstrap"
final_resolver = "remote"
resolvers = [
  { tag = "bootstrap", address = "udp://1.1.1.1", path = "bootstrap" },
  { tag = "remote", address = "https://dns.google/dns-query", path = "proxy" },
  { tag = "local", address = "udp://192.168.1.1", path = "direct" },
]
rules = [
  { domain = ["router.example"], domain_suffix = ["lan.example"], resolver = "local" },
]

[dns.listener]
enabled = true
host = "127.0.0.1"
port = 1053

Remove legacy dns.servers entries when migrating to named resolvers. Tags must be unique; the xrat- prefix and managed inbound tags such as socks-in, tun-in and api belong to generated internal services. Exact and suffix matchers within a rule mean OR. Rules are ordered before the final resolver. Explicit hosts and successful system-hosts answers take precedence. Xray rejects overlapping rules because its DNS server selection cannot preserve the same first-match contract as sing-box. Sing-box named policies require an explicit UseIP, UseIPv4 or UseIPv6 strategy; UseSystem has no exact mapping. Structured resolver/rule arrays are edited in TOML rather than the scalar settings editor.

The bootstrap resolver must use a literal-IP UDP endpoint and path = "bootstrap". XRAT uses bounded A/AAAA queries before replacing a managed session, validates transactions and questions, follows answer-section CNAME chains, and rejects truncated or unsuccessful responses. TCP fallback for this bootstrap step is unsupported. Proxy hostname pinning preserves TLS SNI and transport Host identity. Sing-box uses the bootstrap tag as its explicit domain resolver. Neither backend falls back to the host resolver for configured named bootstrap.

Resolver endpoints accept UDP, TCP and HTTPS on both engines, and TLS on sing-box. Xray rejects DNS-over-TLS. A +local spelling is accepted for migration; the typed path controls egress. Endpoint credentials, query parameters and fragments are rejected. DNS-over-HTTPS keeps its hostname for certificate verification. DNS failure does not authorize fallback from a proxy resolver to direct traffic.

The listener serves UDP and TCP on a loopback IP. Choose an unused port and point applications at it explicitly. Managed TUN additionally intercepts port 53. Encrypted DNS chosen independently by an application is outside that interception. Test and scan processes use real resolver policies without TUN capture or FakeIP allocation.

Xray DNS outbound

Xray 26.7.11 or newer supports an explicit DNS outbound:

[dns.outbound]
tag = "xrat-dns-out"
user_level = 0
rules = [
  { action = "return", domain = ["full:blocked.example"], query_type = [1, 28], response_code = 5 },
  { action = "hijack" },
]

Rules use Xray domain matcher syntax and numeric DNS record types. hijack answers through the configured internal DNS client; direct forwards the DNS message; drop returns no answer; return constructs a response with the chosen rcode (0..15). The default internal outbound remains generated when TUN or the listener needs it. Explicit configuration replaces that outbound instead of adding a second competing DNS path.

Optional rewrite_network = "tcp" or "udp", rewrite_address and rewrite_port control forwarded DNS destinations. They apply to forwarding, not the internal resolver used by hijack. Configured DNS-outbound routing covers port 53 on managed proxy inbounds as well as the DNS listener. Sing-box rejects this Xray-specific block and uses its native hijack-dns action instead.

FakeIP

Enable FakeIP only after configuring named real resolvers and either the DNS listener or TUN:

[dns.fakeip]
enabled = true
ipv4_range = "198.18.0.0/15"
ipv6_range = ""
pool_size = 65535
exclude = ["router.example"]
persist = false

The IPv4 pool must be a network CIDR within 198.18.0.0/15; an optional IPv6 pool must be a ULA network CIDR. Avoid ranges used by the local network or TUN interface. DNS caching is required for domain recovery. Xray requires query_strategy = "UseIP"; family-only strategies do not allocate FakeIP. pool_size bounds Xray allocations and must fit the IPv4 CIDR. Sing-box uses its CIDR capacity and accepts only the default value for this Xray-specific field.

Explicit hosts retain real answers. Exclusions are exact hostnames: sing-box uses the final real resolver, while Xray resolves a real bootstrap snapshot before startup unless a host override exists. Refresh that snapshot by reconnecting. Xray mappings reset on restart and reject persist = true. Sing-box persistence uses a policy-specific cache with mode 0600 under XRAT’s private runtime directory (0700 on Unix); changing the resolver, pool, rules or hosts selects a different cache. Cache files contain DNS mappings and should remain private to the XRAT user.

Fake addresses work only when connections return through the managed engine. Applications that use cached fake answers after disconnect cannot reach the original destination. FakeIP does not provide a persistent kill switch.

V2Ray advanced DNS, encrypted bootstrap, suffix exclusions and system DNS ownership are explicitly unsupported by this contract.

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

Runtime ownership

CLI connect, disconnect, and rotation operations require the daemon. The TUI checks the daemon before each runtime operation and uses the same IPC control when it is reachable. Without a daemon, the TUI operates standalone. A timeout or invalid daemon response is reported as an error rather than starting a second runtime owner. Daemon internals always use local runtime control.

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 automatically purged when not in use (otherwise retained as 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