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.