Introduction

XStat is an open-source real-time hardware monitoring application for Windows. It reads live sensor data from your CPU, GPU, RAM, storage and network then lets you design and display fully custom panels on your desktop — and on any device on your local network.

System Requirements

Quick Start

The fastest way to get XStat running:

1. Download the latest XStat Setup.exe from the Releases page.
2. Run the installer as administrator.
3. XStat starts automatically and appears in the system tray. Double-click the tray icon to open the main window.

Installer Recommended

The NSIS installer handles everything automatically — service registration, shortcuts, and startup entry.

1. Download

Go to the Releases page and download XStat Setup <version>.exe from the latest release.

2. Run the installer

Double-click the installer. Windows may show a SmartScreen warning — click "More info" → "Run anyway" (the app is not yet code-signed).

The installer will:

• Install XStat to %ProgramFiles%\XStat
• Register XStatHardwareSvc as a Windows Service running as Local System
• Create a Start Menu shortcut
• Add an optional Desktop shortcut
• Configure a Windows startup entry (can be disabled)

3. First launch

XStat starts automatically after installation. Look for the XStat icon in the system tray. Double-click it to open the main window.

Portable ZIP

No installer needed. Extract the portable ZIP anywhere and run XStat.exe directly.

1. Download XStat-Portable-<version>.zip from the Releases page.
2. Extract the ZIP to any folder.
3. Right-click XStat.exe → Run as administrator.

From Source

Requires Node.js 20+, .NET 9 SDK, and Windows.

# Clone and install
git clone https://github.com/Inside4ndroid/XStat-Hardware-Monitoring.git
cd XStat-Hardware-Monitoring/src/app
npm install

# Start in dev mode (will prompt for elevation)
npm run dev:admin

See the Development Setup section for full details.

Firewall & LAN Access

The hardware service listens on port 9421 by default (configurable in Settings). If your Windows Firewall blocks LAN access to the web panel, add an inbound rule:

netsh advfirewall firewall add rule `
  name="XStat Hardware Service" `
  dir=in action=allow protocol=TCP localport=9421

Once the rule is in place, open the XStat app → Settings → scan the QR code or copy the URL to open the LAN panel on any device.

Uninstallation

• Installed via NSIS: Go to Settings → Apps (or Control Panel → Programs) and uninstall XStat. The Windows Service is removed automatically.
• Portable: Delete the folder. Any user config stored in %APPDATA%\xstat\ can also be removed manually.

Dashboard

The Dashboard is the main view. It groups sensor data by hardware category and updates in real time via a SignalR WebSocket connection to the hardware service.

Sensor categories

Panel Editor

The Panel Editor lets you design a fully custom display panel using a drag-and-drop dot-grid canvas.

Basic workflow

1. Click a widget type in the Add Widget sidebar to add it to the canvas.
2. Drag to reposition; drag the resize handle to change size.
3. Select a widget and use the Properties panel on the right to bind it to a sensor and style each element.
4. Use the z-index controls (Send to Back / Bring to Front) to layer widgets.
5. Click the panel name in the toolbar to rename it or switch between multiple panels.
6. Use the Export / Import buttons to save or load panel layouts as JSON.

Canvas settings

The canvas size (W × H in pixels) determines the dimensions of your panel when viewed in the LAN browser. Set it to match your secondary monitor or streaming overlay resolution.

LAN Web Panel

Every panel you build is simultaneously served as a web page by the hardware service. Any device on the same network can view it in a browser — no app install required.

Finding the URL

Go to Settings → LAN Web Panel. The URL (e.g. http://192.168.1.128:9421) and a QR code are shown. Scan the QR code with your phone or paste the URL into any browser.

Reconnection

The LAN panel automatically reconnects if the service restarts. If the panel is showing stale content, hard-refresh the browser (Ctrl+Shift+R).

Settings

Settings are persisted to %APPDATA%\xstat\xstat-config.json.

Overview

The XStat Android companion app automatically discovers your XStat PC on the local network using UDP broadcast and displays your custom sensor panel in a full-screen WebView. No IP addresses to configure.

Screenshots

Installing the APK

1. Download XStat-Companion-0.3.0.apk from the Releases page.
2. On your Android device, open Settings → Security (or Privacy on some devices) and enable Install unknown apps for your file manager or browser.
3. Open the downloaded APK file and tap Install.
4. Once installed, open XStat from your app drawer. Make sure your phone/tablet is on the same Wi-Fi network as your PC.

Android TV / SHIELD

Sideload the APK via ADB or a USB file manager. The app includes a TV-optimised leanback launcher entry and a 320×180 TV banner.

adb connect <shield-ip>:5555
adb install -r XStat-Companion-0.3.0.apk
adb shell am start -n net.xstat.companion/.SplashActivity

Auto-Discovery

XStat uses a UDP broadcast beacon to announce itself on the local network. The Android app listens for this beacon and connects automatically — no manual configuration required.

The beacon is sent by the DiscoveryBeaconService background service running inside the .NET hardware service process on the PC. No additional firewall rules are required for UDP broadcast within the same subnet.

Connection health monitoring

Once connected, the app pings /health on the XStat service every 5 seconds. After 3 consecutive failures (15 seconds total) it concludes the host is offline and returns to the discovery splash screen to search again.

Android TV

The companion app fully supports Android TV. It ships with a 320×180 TV banner and registers a leanback launcher entry so it appears in your TV's app grid.

The app runs in full-screen immersive mode with no navigation bars or status bar. On TV remote, the Back button is intercepted for WebView history navigation before exiting.

Common Properties

Every widget in the panel editor shares these base properties:

Sensor Value

Displays a single sensor reading as a large number with an optional label and unit. Best for spotlighting a single metric at a glance.

Best for: CPU temperature, GPU load, RAM usage, fan speeds.

Sensor Bar

A horizontal progress bar showing a sensor value against a configurable min/max range. Good for load percentages.

Sparkline

An area chart displaying the last 60 data points for a sensor. Great for spotting trends and load spikes over time.

Gauge

A circular arc gauge with a coloured fill over a subtle track. Clean and compact for percentage-based metrics.

Clock

Displays the current local time, updating every second. Supports configurable format, font, and colour.

Text

A static text label. Use it for section headings, decorative text, or anything static on your panel.

Image

Display any image on your panel. Use it for a logo, background, watermark, or decorative graphic.

Custom HTML Widget

Write completely bespoke widgets using HTML, CSS, and JavaScript in the built-in Monaco editor. Live preview updates as you type. Sensor data is injected via a postMessage API.

Sensor data API

The widget iframe receives a message event whenever sensor data updates. Listen for it like this:

window.addEventListener('message', (e) => {
  const sensors = e.data.sensors; // HardwareSnapshot object
  // Access any sensor value, e.g.:
  const cpuTemp = sensors?.cpu?.temperature;
});

Files panel

The Files (N) button in the editor toolbar lets you upload assets (images, fonts, data files) that are bundled with the widget. Reference them by filename in your HTML.

Tips

• Set background: transparent on the body to blend with the panel background.
• Use overflow: hidden to prevent content from spilling outside the widget bounds.
• The live preview reflects the last saved sensor snapshot — click Run to force a refresh.

Prerequisites

Dev Setup

1 — Clone & install

git clone https://github.com/Inside4ndroid/XStat-Hardware-Monitoring.git
cd XStat-Hardware-Monitoring/src/app
npm install

2 — Start the dev server

The dev:admin script launches the Vite dev server and the Electron shell together, prompting for administrator elevation so the hardware service can access sensors.

npm run dev:admin

This runs dev-admin.ps1 which:

1. Re-launches the PowerShell session elevated (UAC prompt).
2. Starts the .NET hardware service in the background.
3. Runs electron-vite dev — the React Vite HMR server and Electron window.

3 — Rebuild the LAN panel

When you change panel-related React code and want the LAN panel to reflect it, rebuild the panel bundle:

npm run build:panel

Project Layout

xstat/
├── src/
│   ├── app/                    # Electron + React frontend
│   │   ├── electron/
│   │   │   ├── main.ts         # Main process
│   │   │   └── preload.ts      # Context bridge
│   │   └── src/
│   │       ├── pages/          # Dashboard, PanelEditor, Settings, WidgetEditor
│   │       ├── components/     # Shared UI components
│   │       ├── hooks/          # useSensors, usePanelLayout, useAppSettings
│   │       └── types/          # TypeScript definitions
│   └── XStat.Service/          # ASP.NET Core hardware service
│       ├── Controllers/        # REST API
│       ├── Hardware/           # LibreHardwareMonitor wrapper
│       ├── Hubs/               # SignalR sensor hub
│       └── Services/           # SensorBroadcastService
├── website-source/             # This website (GitHub Pages)
├── build.ps1                   # Full production build script
└── xstat.sln                   # Visual Studio solution

Production Build

Run the build script from the repo root. It publishes the .NET service, builds the React bundles, and packages the Electron app into an NSIS installer and a portable ZIP.

.\build.ps1

Output artifacts are placed in dist\:

• XStat Setup <version>.exe — NSIS installer
• XStat-Portable-<version>.zip — portable build
• win-unpacked\ — unpacked app directory

Overview

XStat is composed of two independent processes that communicate over HTTP and WebSockets.

Electron Process

Main process (main.ts)

• Service lifecycle — probes /health, tries to start the registered Windows Service, falls back to spawning the .exe directly.
• Window management — main window (custom frame) and a detached widget editor window.
• IPC handlers — exposes service:url, service:setPort, window:*, app:quit, and widget-editor:* channels.
• System tray — closing the main window hides it to the tray rather than quitting.

Preload (preload.ts)

Bridges main process to renderer via contextBridge.exposeInMainWorld('xstat', ...). The renderer has no direct Node access — all native operations go through the typed window.xstat API.

Hardware Service

An ASP.NET Core 9 web application that wraps LibreHardwareMonitor and exposes sensor data over HTTP and WebSockets.

• Listens on 0.0.0.0:{port} — required for LAN browser access.
• Supports running as a Windows Service (UseWindowsService) or as a console app.
• SensorBroadcastService polls hardware at the configured interval and sends snapshots to all SignalR clients.
• Serves the panel React bundle as static files from wwwroot/.

REST API

Data Flow

LibreHardwareMonitor
        │  poll every N ms
        ▼
SensorBroadcastService
        │  SignalR broadcast
    ┌───┴──────────────────────┐
    ▼                          ▼
Electron Renderer          LAN Browser
(useSensors hook)          (PanelApp.tsx)
        │                      │
   HardwareSnapshot       HardwareSnapshot
        │                      │
  Widget renderers        Widget renderers
        │                      │
  Live panel display      Live panel display

Security Notes

• CORS is restricted to localhost, Electron (file://), and private IP ranges only.
• No authentication is implemented on the service endpoints.
• The Electron renderer runs with contextIsolation: true and nodeIntegration: false. All Node access is via the typed preload bridge.