daemon

Run or control the daemon supervisor process.

xrat daemon <action>

Actions

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

daemon start

Start the long-lived daemon supervisor process.

xrat daemon start

Flags

No command-specific flags.

Behavior

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

Daemon Features

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

daemon status

Show daemon IPC reachability and protocol information.

xrat daemon status

Flags

No command-specific flags.

Output

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

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

daemon stop

Request daemon shutdown via local IPC.

xrat daemon stop

Flags

No command-specific flags.

Behavior

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

daemon restart

Restart the daemon after editing config.toml.

xrat daemon restart

Flags

No command-specific flags.

Behavior

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

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

daemon install

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

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

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

Flags

Behavior (Linux/systemd)

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

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

Example

xrat daemon install --start

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

Daemon installed successfully.

Dry run

xrat daemon install --dry-run

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

daemon uninstall

Remove the installed xrat-daemon background service (systemd/launchd/rc.d depending on the OS).

xrat daemon uninstall [--dry-run]

Flags

Behavior (Linux/systemd)

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

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

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

IPC Protocol

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

Request Types

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

Response Envelope

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

Related

• rotate — control auto-rotation scheduling
• proxy — local proxy endpoints, shell, desktop, and PAC helpers
• connect — start a proxy via daemon IPC
• status — check proxy status via daemon IPC
• init — initialize config directory before first use
• systemd — full systemd deployment guide