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

Argument	Description
`ref`	Config ref prefix to start as the active session

Flags

Flag	Description
`--json`	Print the result as JSON

Examples

xrat connect a1b2

xrat connect a1b2c3d4 --json

Behavior

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

If the daemon is not running, start it first:

xrat daemon start

Default Inbounds

Protocol	Host	Port	Notes
SOCKS5	`0.0.0.0`	`18200`	UDP support enabled by default
HTTP	`0.0.0.0`	`18201`	Disabled by default in config.toml
Shadowsocks	`0.0.0.0`	`18202`	Disabled by default, aes-128-gcm

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.

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

disconnect

Stop the active managed proxy runtime.

xrat disconnect [flags]

Flags

Flag	Description
`--json`	Print the result as JSON

Examples

xrat disconnect

Behavior

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

status

Show the managed proxy runtime status.

xrat status [flags]

Flags

Flag	Description
`--json`	Print the status as JSON

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

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

Keyboard shortcuts