xBeacon

xBeacon is a cross-platform notification system for VDI environments consisting of:

• xBeacon Windows - System tray app with WPF dashboard (Windows 11+)
• xBeacon CLI - Daemon with libnotify notifications (Linux)
• xBeacon Server - Cross-platform notification server with web dashboard and API

Use Case

Designed for VDI (Virtual Desktop Infrastructure) environments where administrators need to notify users about:

• Session time remaining - How much time is left in their reservation
• Support information - Where to get help
• System announcements - Maintenance windows, alerts, etc.

Features

• Single portable executable (~15-30MB)
• Cross-platform: Windows tray app or Linux CLI daemon
• Smart HTTP caching (ETag/Last-Modified)
• Exponential backoff on errors
• Optional run-at-startup (Task Scheduler on Windows, systemd on Linux)
• Platform-agnostic (works on any VDI platform)

Quick Start

Windows Client

1. Download xBeacon-win-x64.exe from Releases
2. Create config.json next to it:

   {
     "url": "https://your-server.com/notifications",
     "headers": {
       "X-API-Key": "xbk_your_api_key_here"
     },
     "pollIntervalSeconds": 60
   }

3. Run xBeacon-win-x64.exe

Linux CLI

1. Download xBeacon-linux-x64 from Releases
2. Create config file at ~/.config/xbeacon/config.json:

   {
     "url": "https://your-server.com/notifications",
     "headers": {
       "X-API-Key": "xbk_your_api_key_here"
     },
     "pollIntervalSeconds": 60
   }

3. Run the daemon:

   chmod +x xBeacon-linux-x64
   ./xBeacon-linux-x64 daemon

Server (Cross-platform)

1. Download xBeaconServer-* for your platform from Releases
2. Run the server:

   # Windows
   ./xBeaconServer-win-x64.exe
   
   # Linux
   ./xBeaconServer-linux-x64
   
   # macOS
   ./xBeaconServer-osx-arm64

3. Generate an API key:

   ./xBeaconServer-* generate-key --name "VDI Pool 1"

4. Access the web dashboard at http://localhost:5100

Components

xBeacon Windows

• Single portable executable (~15-30MB)
• Runs in Windows system tray
• WPF dashboard popup with notification history
• Smart HTTP caching (ETag)
• Exponential backoff on errors
• Optional run-at-startup via Task Scheduler

xBeacon CLI (Linux)

• Single portable executable
• Daemon mode with libnotify integration
• Console fallback when libnotify unavailable
• Systemd service support
• XDG-compliant config paths

xBeacon Server

• Cross-platform (Windows, Linux, macOS)
• Web dashboard for management
• API key authentication (prefix: xbk_)
• Notification scheduling
• File-based storage (no database)
• Single executable deployment
• Windows Service / systemd support

Documentation

• User Guide - Client installation and usage
• Server Guide - Server deployment and configuration
• Architecture - System design
• Release Process - How to create releases
• ADRs - Architecture decisions
• spec.yaml - Single source of truth for all features and components

Architecture

                              HTTP GET
                         X-API-Key: xbk_...
                         JSON notifications
                                │
                                ▼
                      ┌──────────────────┐
                      │  xBeacon Server  │
                      │  (Any OS)        │
                      └────────┬─────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
              ▼                ▼                ▼
    ┌─────────────────┐ ┌─────────────┐ ┌──────────────────┐
    │  xBeacon        │ │ xBeacon CLI │ │  Web Dashboard   │
    │  Windows        │ │ (Linux)     │ │  (Browser)       │
    │  (Tray App)     │ │             │ │                  │
    └────────┬────────┘ └──────┬──────┘ └──────────────────┘
             │                 │
             ▼                 ▼
    ┌─────────────────┐ ┌─────────────┐
    │ Windows Toast   │ │ libnotify   │
    │ Notifications   │ │ Popups      │
    └─────────────────┘ └─────────────┘