🚀 BetterDesk Console

A modern, feature-rich web management console for RustDesk with real-time device monitoring and bidirectional ban enforcement

Features • Screenshots • Installation • Documentation • Contributing

---

📋 Table of Contents

• Quick Start
• Overview
• Features
• Screenshots
• Architecture
• Installation
  • Linux
  • Windows
  • Docker
• Internationalization
• Troubleshooting
• Configuration
• API Documentation
• Development
• Technology Stack
• Contributing
• License
• Credits

---

🚀 Quick Start

BetterDesk 2.2 introduces Node.js web console (recommended) alongside the original Flask console.

Linux

git clone https://github.com/UNITRONIX/Rustdesk-FreeConsole.git
cd Rustdesk-FreeConsole
chmod +x betterdesk.sh

# Interactive mode (choose console type)
sudo ./betterdesk.sh

# Automatic with Node.js console (recommended)
sudo ./betterdesk.sh --auto --nodejs

# Automatic with Flask console (legacy)
sudo ./betterdesk.sh --auto --flask

Windows (PowerShell as Administrator)

git clone https://github.com/UNITRONIX/Rustdesk-FreeConsole.git
cd Rustdesk-FreeConsole

# Interactive mode (choose console type)
.\betterdesk.ps1

# Automatic with Node.js console (recommended)
.\betterdesk.ps1 -Auto -NodeJs

# Automatic with Flask console (legacy)
.\betterdesk.ps1 -Auto -Flask

Docker

git clone https://github.com/UNITRONIX/Rustdesk-FreeConsole.git
cd Rustdesk-FreeConsole
chmod +x betterdesk-docker.sh
./betterdesk-docker.sh

All scripts offer an interactive menu with options:

1. 🚀 Fresh Installation (Node.js or Flask console)
2. ⬆️ Update
3. 🔧 Repair Installation
4. ✅ Validate Installation
5. 💾 Backup
6. 🔐 Reset Admin Password
7. 🔨 Build Binaries
8. 📊 Diagnostics
9. 🗑️ Uninstall S. ⚙️ Settings (path configuration)

---

🌟 Overview

BetterDesk Console is an enhanced web management interface for RustDesk - the open-source remote desktop solution. It extends the standard RustDesk HBBS (HBB Signal Server) with a powerful HTTP API and provides a beautiful, modern web interface for managing your RustDesk infrastructure.

🤖 AI-Assisted Development: This project was developed with significant assistance from AI coding tools (Claude/GitHub Copilot). While all code has been reviewed, tested, and validated for production use, users should be aware of this development approach.

Why BetterDesk Console?

• Real-Time Monitoring: See which devices are online/offline instantly
• Beautiful UI: Modern glassmorphism design with Material Icons
• Authentic Status Detection: Uses the same algorithm as RustDesk desktop client
• RESTful API: Easy integration with other tools and scripts
• Device Management: Add notes, search, filter, and organize your devices
• Open Source: Fully transparent and customizable

---

✨ Features

🎨 Modern Web Interface

• Glassmorphism Design: Sleek, modern UI with blur effects and gradients
• Material Icons: Google Material Design icons (fully offline)
• Responsive Layout: Works on desktop and tablet
• Dark Theme: Easy on the eyes, perfect for NOC environments
• Real-Time Updates: Auto-refresh device status
• Search & Filter: Quickly find devices in large deployments

🔧 Enhanced HBBS Server

• HTTP API: RESTful API on port 21120 with X-API-Key authentication (LAN accessible)
• Real-Time Status: Memory-based device status (no database lag)
• Database Fallback: Web console automatically falls back to SQLite database when API unavailable
• Smart Status Detection: HBBS automatically updates device status in database during connections
• Authentic Algorithm: Uses RustDesk's official 30-second timeout logic
• Thread-Safe: Shared PeerMap with Arc/RwLock for concurrent access
• Zero Breaking Changes: Fully compatible with existing RustDesk clients
• CORS Support: Easy web console integration
• 🔥 Bidirectional Ban Enforcement (v8):
  • Prevents banned devices from initiating connections (source check)
  • Prevents connections to banned devices (target check)
  • Works for both P2P and relay connections
  • Real-time database sync - no restart required

📊 Device Management

• Dashboard View: Overview with statistics cards (Total, Active, Inactive, Banned, With Notes)
• Device List: Sortable table with ID, notes, status, and timestamps
• Device Details: View complete device information including ban status
• Add Notes: Label devices with custom descriptions
• 🔒 Device Banning: Ban/unban devices with reason tracking and administrator info
  • Bidirectional Enforcement (v8): Banned devices blocked in both directions
  • Source ban: Banned device cannot initiate any connections
  • Target ban: Cannot connect to banned devices
  • Enforced at punch hole and relay request stages
  • 100% reliability with real-time sync
• Soft Delete: Devices marked as deleted (recoverable) instead of permanent removal
• Batch Operations: Search and filter multiple devices
• Public Key Display: Quick access to server public key
• Visual Indicators: Color-coded status badges, banned device highlighting

🔧 Client Generator (UNDER DEVELOPMENT)

⚠️ STATUS: IN DEVELOPMENT - NOT YET FUNCTIONAL
This feature is currently under active development and is not ready for production use. The UI is accessible but the functionality is not yet implemented. Expected completion: TBD.

Planned features:

• 🚀 Custom RustDesk Client Builder: Generate pre-configured RustDesk clients directly from the web panel
• Multi-Platform Support: Windows (64/32-bit), Linux, Android, macOS
• Version Selection: Choose from multiple RustDesk versions (1.4.2 - 1.4.5)
• Pre-Configuration: Embed server settings, security options, and permissions
• Visual Customization: Upload custom icons and logos
• Security Options: Set permanent passwords, approve modes, LAN discovery
• Permission Control: Granular control over features (clipboard, file transfer, audio, etc.)
• Branding: Custom company name, URLs, and copyright information
• Code Changes: Optional modifications (monitor cycling, offline indicators, version notifications)
• One-Click Deployment: Download ready-to-deploy clients with all settings embedded
• Audit Logging: All client generations are logged for security tracking

See Client Generator Documentation for planned feature details.

🛡️ Security & Reliability

• Authentication System (v1.5.0):
  • User login with bcrypt password hashing
  • Role-based access control (Admin, Operator, Viewer)
  • Session management with 24-hour tokens
  • \ud83c\udf10 Sidebar navigation with 5 main sections (Dashboard, Public Key, Settings, User Management, About)
  • \ud83d\udd11 Password-protected public key access - requires password verification
  • \u2699\ufe0f Settings page with password change functionality
  • \ud83d\udc65 User management panel (admin only) - create, edit, delete, activate/deactivate users
  • \ud83d\udcdd Extended About page with open source credits and license information
  • Audit logging for all actions
• API Security (v1.4.0):
  • X-API-Key header authentication for HBBS API
  • 64-character random API keys
  • Secure key storage with 600 permissions
  • LAN accessible (0.0.0.0) with authentication protection
• Input Validation: Comprehensive validation for all user inputs
• XSS Protection: Sanitization of user-provided content
• SQL Injection Prevention: Parameterized queries throughout
• Bidirectional Ban Enforcement (v8):
  • Source device ban check (prevents banned devices from connecting)
  • Target device ban check (prevents connections to banned devices)
  • No race conditions or timing vulnerabilities
  • Minimal performance impact (~1ms per check)
• Ban Management: Track who banned devices, when, and why
• Confirmation Dialogs: Explicit confirmation for destructive operations
• Automatic Backups: Installation and update scripts create safety backups
• Precompiled Binaries: No compilation needed, faster deployment
• Service Management: Systemd integration for auto-restart
• Graceful Degradation: Web console works even if API is unavailable
• No External Dependencies: All assets served locally (offline-ready)
• Audit Trail: Timestamps for all device modifications

🌍 Internationalization (i18n)

BetterDesk Console supports multiple languages through a JSON-based translation system.

Features:

• Auto-Detection: Automatically detects browser language preference
• Manual Selection: Change language via Settings → Language Settings
• Persistent: Language preference saved in cookies (1 year)
• Community Translations: Easy to add new languages via JSON files
• Custom Upload: Upload your own language packs directly from the web panel

Built-in Languages:

• 🇬🇧 English (default)
• 🇵🇱 Polish (Polski)

Adding a Custom Language:

1. Go to Settings → Language Settings
2. Click Choose JSON File and select your translation file
3. The language will be available immediately after upload
4. Refresh the page to apply translations

Creating a Language Pack:

1. Copy web/lang/en.json to web/lang/[code].json
2. Translate all string values
3. Update the _meta section with language info
4. Upload via the web panel or place in the lang/ folder

See Contributing Translations for detailed instructions.

---

📸 Screenshots

Dashboard Overview

Real-time statistics and device status overview

Device Management

Comprehensive device list with search and filtering

Device Details

Detailed device information modal

Public Key Management

Secure public key access with password protection

Settings

User settings and password management

User Management

Multi-user administration panel

About

System information and version details

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                   RustDesk Clients                      │
│              (Desktop, Tablet, Web)                      │
└──────────────────────┬──────────────────────────────────┘
                       │ Heartbeat (~30-45s)
                       ▼
         ┌─────────────────────────────┐
         │   Enhanced HBBS Server      │
         │   (Port 21115-21119)        │
         └──────────┬──────────────────┘
                    │
                    ▼
         ┌─────────────────────────────┐
         │   Arc<PeerMap>              │
         │   (Shared Memory)           │
         │   • In-memory peer storage  │
         │   • last_reg_time tracking  │
         └──────────┬──────────────────┘
                    │
         ┌──────────┴──────────┐
         ▼                     ▼
┌────────────────┐   ┌─────────────────┐
│  HTTP API      │   │  SQLite DB      │
│  (Port 21120)  │   │  (Persistence)  │
│  (LAN Access)  │   │                 │
└────────┬───────┘   └─────────────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│       Web Management Console            │
│              (Port 5000)                │
├─────────────────┬───────────────────────┤
│  Node.js        │  Flask (Legacy)       │
│  (Recommended)  │  (Python)             │
│  Express.js     │  Jinja2 templates     │
│  EJS templates  │                       │
│  better-sqlite3 │                       │
└─────────────────┴───────────────────────┘

Key Components

1. Enhanced HBBS: Modified RustDesk signal server with HTTP API
2. HTTP API: Axum-based REST API for device queries
3. PeerMap: Thread-safe in-memory peer storage (Arc)
4. Web Console: Node.js (recommended) or Flask application with modern UI
5. SQLite Database: Original RustDesk database (unchanged)

Web Console Options

Feature	Node.js (Recommended)	Flask (Legacy)
Performance	Faster, non-blocking	Good
Memory	Lower	Higher
Dependencies	npm packages	Python venv
Database	better-sqlite3	sqlite3
Templates	EJS	Jinja2
Startup Time	~1 second	~3 seconds

---

🚀 Installation

📌 Interactive ALL-IN-ONE Scripts (v2.2.0 - Recommended)

Platform	Script	Features
Linux	betterdesk.sh	✅ Interactive menu, Node.js/Flask choice, install, update, backup, diagnostics
Windows	betterdesk.ps1	✅ Interactive menu, Node.js/Flask choice, install, update, backup, diagnostics
Docker	betterdesk-docker.sh	✅ Interactive menu, build images, manage containers

💡 New in v2.2.0: Choose between Node.js (recommended) and Flask web console during installation!

🐧 Linux (betterdesk.sh)

git clone https://github.com/UNITRONIX/Rustdesk-FreeConsole.git
cd Rustdesk-FreeConsole
chmod +x betterdesk.sh

# Interactive mode
sudo ./betterdesk.sh

# Automatic mode with Node.js (recommended)
sudo ./betterdesk.sh --auto --nodejs

🪟 Windows (betterdesk.ps1)

git clone https://github.com/UNITRONIX/Rustdesk-FreeConsole.git
cd Rustdesk-FreeConsole

# Interactive mode (Run as Administrator)
.\betterdesk.ps1

# Automatic mode with Node.js (recommended)
.\betterdesk.ps1 -Auto -NodeJs

🐳 Docker (betterdesk-docker.sh)

git clone https://github.com/UNITRONIX/Rustdesk-FreeConsole.git
cd Rustdesk-FreeConsole
chmod +x betterdesk-docker.sh
./betterdesk-docker.sh

---

� Docker Installation (Alternative)

For containerized deployments using Docker Compose:

git clone https://github.com/UNITRONIX/Rustdesk-FreeConsole.git
cd Rustdesk-FreeConsole

# Build and start (REQUIRED - images are not on Docker Hub)
docker compose build
docker compose up -d

Full Docker guide: DOCKER_TROUBLESHOOTING.md

Prerequisites

• Linux: Ubuntu 20.04+, Debian 11+, CentOS 8+, Arch Linux
• Windows: Windows 10+, Windows Server 2016+
• RustDesk: Fresh RustDesk installation OR existing working HBBS (script auto-detects)
• Node.js Console: Node.js 18+ (auto-installed by script)
• Flask Console: Python 3.8+ (auto-installed by script)
• No Compilation Required: Uses precompiled binaries

💡 Fresh Installation Support: The script automatically detects if you have RustDesk installed and can perform fresh installations or updates accordingly. No need for separate installation procedures!

🐳 Docker Installation (Alternative)

For containerized deployments using Docker Compose:

git clone https://github.com/UNITRONIX/Rustdesk-FreeConsole.git
cd Rustdesk-FreeConsole

# Build and start (REQUIRED - images are not on Docker Hub)
docker compose build
docker compose up -d

Full Docker guide: docs/DOCKER_TROUBLESHOOTING.md

What the installation scripts do

• ✅ Detects existing RustDesk installation
• ✅ Creates automatic backup
• ✅ Installs BetterDesk enhanced binaries
• ✅ Installs web console (Node.js or Flask)
• ✅ Runs database migrations
• ✅ Creates authentication tables and admin user
• ✅ Configures system services (systemd/Windows services)
• ✅ Preserves encryption keys

🔄 Updating Existing Installation

# Linux
cd Rustdesk-FreeConsole
git pull origin main
sudo ./betterdesk.sh  # Select option 2: Update

# Windows (PowerShell as Administrator)
cd Rustdesk-FreeConsole
git pull origin main
.\betterdesk.ps1  # Select option 2: Update

Quick Database Fix (if devices show as offline)

Note

: The betterdesk.sh / betterdesk.ps1 scripts run database migrations automatically. Use manual steps only if needed.

# Linux - Use repair option
sudo ./betterdesk.sh  # Select option 3: Repair

# Or run migration manually
python3 migrations/v1.5.0_fix_online_status.py
sudo systemctl restart rustdesksignal betterdesk

# Windows - Use repair option
.\betterdesk.ps1  # Select option 3: Repair

⚠️ Platform-Specific Binaries

The installers automatically select correct binaries for your platform:

Platform	Binaries	API Port
Linux x86_64	hbbs-patch-v2/hbbs-linux-x86_64, hbbr-linux-x86_64	21120
Windows x86_64	hbbs-patch-v2/hbbs-windows-x86_64.exe, hbbr-windows-x86_64.exe	21114

Note

: Do not mix binaries between platforms!

🔑 Key Protection (IMPORTANT!)

⚠️ Your RustDesk encryption keys are CRITICAL!

• Losing keys = ALL clients disconnected
• Changing keys = "Key mismatch" errors on all devices
• Keys must be backed up before any installation

BetterDesk automatically:

• ✅ Detects existing encryption keys
• ✅ Creates automatic backups before any changes
• ✅ Never regenerates keys without explicit confirmation

If you experience "Key mismatch" errors:

# Restore from automatic backup
BACKUP=$(ls -d /opt/rustdesk-backup-* | sort | tail -1)
sudo cp $BACKUP/id_ed25519* /opt/rustdesk/
sudo systemctl restart rustdesksignal

📖 Full guide: docs/KEY_TROUBLESHOOTING.md

---

🔧 Troubleshooting

⚡ Recent Fixes (31 Jan 2026)

🐛 Fixed Issues:

• ✅ Docker: "sh: executable file not found" - Added bash to Dockerfile
• ✅ PowerShell: "Write-Info is not recognized" - Fixed function naming conflicts
• 📖 QUICK_FIX.md - Quick solutions for reported problems
• 📖 TROUBLESHOOTING.md - Complete troubleshooting guide

---

🚨 "The keys do not match" Error

This is the most common issue after installation. Don't panic!

Quick Fix - Restore from backup:

# Find most recent backup
BACKUP=$(ls -d /opt/rustdesk-backup-* | sort | tail -1)

# Restore keys
sudo systemctl stop rustdesksignal rustdeskrelay
sudo cp $BACKUP/id_ed25519* /opt/rustdesk/
sudo chmod 600 /opt/rustdesk/id_ed25519
sudo chmod 644 /opt/rustdesk/id_ed25519.pub
sudo systemctl start rustdesksignal rustdeskrelay

# Verify
cat /opt/rustdesk/id_ed25519.pub

📚 Comprehensive Troubleshooting Guides

• QUICK_FIX.md - Fast solutions for recent user-reported issues
• TROUBLESHOOTING.md - Docker & PowerShell fixes
• KEY_TROUBLESHOOTING.md - Complete key management guide
• UPDATE_GUIDE.md - Updating existing installations

🔧 Key Permission Issues

If you experience key permission problems, fix them manually:

# Set correct permissions for encryption keys
sudo chmod 600 /opt/rustdesk/id_ed25519
sudo chmod 644 /opt/rustdesk/id_ed25519.pub

# Restart services
sudo systemctl restart rustdesksignal rustdeskrelay betterdesk

# Verify public key is readable
cat /opt/rustdesk/id_ed25519.pub

🐳 Docker Issues

Problem: "Docker RustDesk installation detected" message

Solutions:

1. Use Docker-compose (recommended for Docker setups)
2. Install web console only (option 2 during installation)
3. Continue with native installation (if intentional)

🔑 Missing Admin Login Credentials (Docker Compose)

Problem: After running docker compose up -d, the console doesn't show admin credentials.

Quick Fix - Use the fix script:

# Linux/macOS
chmod +x fix-admin.sh
./fix-admin.sh

# Windows
fix-admin.bat

Or set custom credentials in docker-compose.yml:

environment:
  - ADMIN_USERNAME=admin
  - ADMIN_PASSWORD=YourSecurePassword123

Manual option (if scripts don't work):

# Run migration in container
docker compose exec betterdesk-console python3 -c "
import sqlite3, secrets, bcrypt
from datetime import datetime

DB_PATH, USERNAME = '/opt/rustdesk/db_v2.sqlite3', 'admin'
PASSWORD = secrets.token_urlsafe(12)
conn = sqlite3.connect(DB_PATH)
cursor = conn.cursor()

# Create tables
cursor.execute('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, username VARCHAR(50) UNIQUE NOT NULL, password_hash TEXT NOT NULL, role VARCHAR(20) NOT NULL DEFAULT \"viewer\", created_at DATETIME NOT NULL, last_login DATETIME, is_active BOOLEAN NOT NULL DEFAULT 1, CHECK (role IN (\"admin\", \"operator\", \"viewer\")))')

# Create admin if missing
cursor.execute('SELECT id FROM users WHERE username = ?', (USERNAME,))
if not cursor.fetchone():
    password_hash = bcrypt.hashpw(PASSWORD.encode(), bcrypt.gensalt()).decode()
    cursor.execute('INSERT INTO users (username, password_hash, role, created_at, is_active) VALUES (?, ?, \"admin\", ?, 1)', (USERNAME, password_hash, datetime.now()))
    print(f'🔐 Username: {USERNAME}\\nPassword: {PASSWORD}\\n⚠️  Change after login!')
else:
    print('ℹ️  Admin user already exists')

conn.commit()
conn.close()
"

---

After using any option above:

1. 🌐 Open: http://localhost:5000
2. 🔑 Login with the displayed/chosen credentials
3. ⚠️ Immediately change password in settings!

Detailed Docker troubleshooting guide: DOCKER_TROUBLESHOOTING.md

Common Issues & Solutions

Symptom	Cause	Solution
"Key mismatch"	Keys changed during install	Restore from backup (see Troubleshooting above)
Wrong key in WebConsole	Multiple .pub files	Remove incorrect files or upgrade to v9+
Services won't start	Permission issues	Fix with: sudo chmod 600 /opt/rustdesk/id_ed25519
Can't find backups	Skipped backup during install	Check /opt/rustdesk-backup-* directories
Docker detected	Running RustDesk in container	Choose "Web Console only" option
No admin login (Docker)	Missing database migration	Run ./fix-admin.sh or see Docker Issues section
All devices offline	Missing last_online column	Run python3 migrations/v1.5.0_fix_online_status.py
API not responding	Old/wrong binaries	Use v2 binaries from hbbs-patch-v2/ (port 21120)
Update script not found	Old version cloned	Run git pull to get latest files
Connect button not working	Custom RustDesk client	Set custom scheme via browser console (see below)
"no such table: peer"	Using original RustDesk binaries	Rebuild Docker: docker compose build --no-cache
"pull access denied"	Images not on Docker Hub	Build locally: docker compose build && docker compose up -d
DNS failure in Docker build	Resolver issues (AlmaLinux/CentOS)	See DOCKER_TROUBLESHOOTING.md

🚨 Known Issues (v1.5.0)

1. Devices Show as Offline After Update

Symptoms: All devices appear offline in the console, even though they can connect to each other.

Cause: Database is missing the last_online column required for status detection.

Solution:

# Option 1: Run migration script
python3 migrations/v1.5.0_fix_online_status.py

# Option 2: Add column manually
sqlite3 /opt/rustdesk/db_v2.sqlite3 "ALTER TABLE peer ADD COLUMN last_online TEXT;"
sqlite3 /opt/rustdesk/db_v2.sqlite3 "ALTER TABLE peer ADD COLUMN is_deleted INTEGER DEFAULT 0;"

# Restart services
sudo systemctl restart hbbs betterdesk

2. Connect Button Not Working (Custom Clients)

Symptoms: Clicking "Connect" does nothing or opens wrong application.

Cause: You have a personalized RustDesk client with custom URL scheme.

Solution: Set your custom scheme via browser console (F12):

// Replace 'mycompany-rustdesk' with your scheme
setCustomScheme('mycompany-rustdesk');

// To revert to default:
clearCustomScheme();

3. API Health Endpoint Not Responding

Symptoms: Console cannot determine device status, shows connection errors.

Cause: Old HBBS binary without API support or using wrong port.

Solution:

# Copy new v2 binary (recommended)
sudo cp hbbs-patch-v2/hbbs-linux-x86_64 /opt/rustdesk/hbbs-v8-api
sudo chmod +x /opt/rustdesk/hbbs-v8-api

# Update service to use new binary
sudo sed -i 's/hbbs/hbbs-v8-api/g' /etc/systemd/system/rustdesksignal.service
sudo systemctl daemon-reload
sudo systemctl restart rustdesksignal

# v2 uses port 21120 (not 21114)

4. Installer Cannot Find Installation

Symptoms: Script reports "Installation directory not found"

Cause: Non-standard installation path.

Solution:

# Find your installation
find / -name "server.js" 2>/dev/null
find / -name "app.py" 2>/dev/null
find / -name "db_v2.sqlite3" 2>/dev/null

# Use Settings menu to configure paths
sudo ./betterdesk.sh  # Select option S: Settings

📞 Getting Help

Before asking for help:

1. Check the troubleshooting guides above
2. Run the diagnostics: sudo ./betterdesk.sh → Select option 8: Diagnostics
3. Collect logs:

   sudo journalctl -u rustdesksignal -n 50 > ~/rustdesk_logs.txt
   sudo journalctl -u betterdesk -n 50 >> ~/rustdesk_logs.txt
   

Where to get help:

• 🐛 GitHub Issues
• 📖 Documentation
• 💬 RustDesk Discussions

---

⚙️ Configuration

HBBS API Port

Default: 21120 (LAN accessible with X-API-Key authentication)

Security (v1.4.0): The API now supports LAN access with proper authentication:

• \u2705 Binds to 0.0.0.0:21120 (accessible on LAN)
• \u2705 Requires X-API-Key header for all requests
• \u2705 64-character random API key generated during installation
• \u2705 Key stored securely in /opt/rustdesk/.api_key with 600 permissions
• \u2705 Web console automatically uses API key
• \u2705 No authentication = no access (secure by design)

API Key Location: /opt/rustdesk/.api_key

To change port, edit /etc/systemd/system/rustdesksignal.service:

ExecStart=/opt/rustdesk/hbbs -k _ -p 21115 --api-port 21120

Web Console Port

Default: 5000 (accessible on LAN)

The web console binds to 0.0.0.0:5000 for LAN access and includes:

• User authentication (bcrypt passwords)
• Session management (24-hour tokens)
• Role-based access control
• Audit logging

Node.js Console: Edit .env file:

PORT=5000

Flask Console: Edit app.py:

app.run(host='0.0.0.0', port=5000)

Firewall Configuration

# Allow web console on LAN
sudo ufw allow from 192.168.0.0/16 to any port 5000 proto tcp

# Allow HBBS API on LAN (v2 uses port 21120)
sudo ufw allow from 192.168.0.0/16 to any port 21120 proto tcp

# Standard RustDesk ports
sudo ufw allow 21115/tcp
sudo ufw allow 21116/tcp
sudo ufw allow 21116/udp
sudo ufw allow 21117/tcp

---

📚 API Documentation

Base URL

http://<server-ip>:21120/api

Authentication

All API requests require X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY_HERE" http://192.168.1.100:21120/api/health

API Key Location: /opt/rustdesk/.api_key

To retrieve your API key:

sudo cat /opt/rustdesk/.api_key

Endpoints

Health Check

GET /api/health
Headers: X-API-Key: <your-api-key>

Response:

{
  "success": true,
  "data": "RustDesk API is running",
  "error": null
}

List All Peers

GET /api/peers
Headers: X-API-Key: <your-api-key>

Response:

{
  "success": true,
  "data": [
    {
      "id": "1234567890",
      "note": "Production Server",
      "online": true
    },
    {
      "id": "9876543210",
      "note": null,
      "online": false
    }
  ],
  "error": null
}

Error Response (No/Invalid API Key):

{
  "error": "Unauthorized: Invalid or missing API key"
}

Status Code: 401

Status Detection Algorithm

A device is considered online if:

1. It exists in the PeerMap (in-memory storage)
2. Last registration time is less than 30 seconds ago

const REG_TIMEOUT: i32 = 30_000; // milliseconds

online = peer_exists && (last_reg_time.elapsed() < REG_TIMEOUT)

This is the exact same algorithm used by RustDesk desktop client.

---

🛠️ Development

Running Demo Version (Mock Data)

For screenshots or testing without real devices:

cd web
python3 app_demo.py

Access at: http://localhost:5001

Project Structure

BetterDeskConsole/
├── README.md                    # This file
├── LICENSE                      # MIT License
├── VERSION                      # Current version number
├── betterdesk.sh                # Linux ALL-IN-ONE installer (v2.2.0)
├── betterdesk.ps1               # Windows ALL-IN-ONE installer (v2.2.0)
├── betterdesk-docker.sh         # Docker installer
├── docker-compose.yml           # Docker orchestration
├── screenshots/                 # UI screenshots
├── web/                         # Flask web console (legacy)
│   ├── app.py                   # Flask application
│   ├── requirements.txt         # Python dependencies
│   └── ...
├── web-nodejs/                  # Node.js web console (recommended)
│   ├── server.js                # Express application
│   ├── package.json             # npm dependencies
│   ├── views/                   # EJS templates
│   ├── public/                  # Static assets (CSS, JS)
│   ├── routes/                  # API routes
│   └── ...
├── hbbs-patch-v2/               # HBBS modifications (v2.x)
│   ├── hbbs-linux-x86_64        # Pre-compiled Linux binary
│   ├── hbbr-linux-x86_64        # Pre-compiled Linux binary
│   ├── hbbs-windows-x86_64.exe  # Pre-compiled Windows binary
│   ├── hbbr-windows-x86_64.exe  # Pre-compiled Windows binary
│   └── src/                     # Source code modifications
├── migrations/                  # Database migration scripts
├── docs/                        # Documentation
├── dev_modules/                 # Development tools
└── scripts/legacy/              # Legacy scripts (deprecated)

Building from Source

# Clone RustDesk server
git clone https://github.com/rustdesk/rustdesk-server.git
cd rustdesk-server

# Copy patched files
cp ../hbbs-patch/src/* src/

# Add dependencies
cargo add axum --features "http1,json,tokio"
cargo add tower-http --features "cors"
cargo add tokio --features "full"

# Build
cargo build --release --bin hbbs

Running Tests

# Test HBBS API
curl http://localhost:21120/api/health

# Test Web Console
curl http://localhost:5000

# Check services
sudo systemctl status rustdesksignal.service
sudo systemctl status betterdesk.service

---

🎨 Technology Stack

Backend

• RustDesk HBBS: Original signal server (AGPL-3.0)
• Rust: Systems programming language
• Axum: Web framework for Rust
• Tokio: Async runtime for Rust
• SQLite: Database (RustDesk original)

Web Console (Node.js - Recommended)

• Node.js: JavaScript runtime (v18+)
• Express.js: Fast, minimalist web framework
• EJS: Embedded JavaScript templating
• better-sqlite3: Fast SQLite3 driver
• bcrypt: Password hashing
• Helmet: Security headers
• express-rate-limit: Rate limiting

Web Console (Flask - Legacy)

• Flask: Python web framework
• Jinja2: Template engine
• bcrypt: Password hashing

Frontend

• HTML5: Semantic markup
• CSS3: Glassmorphism effects, animations, gradients
• JavaScript (ES6+): Dynamic UI updates
• Material Icons: Icon set (offline)

DevOps

• Systemd: Service management (Linux)
• NSSM/Scheduled Tasks: Service management (Windows)
• Docker: Containerization
• Bash/PowerShell: Installation scripting
• Git: Version control

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

Reporting Issues

• Use the GitHub Issues page
• Include system info (OS, RustDesk version, etc.)
• Provide logs from systemd: journalctl -u betterdesk.service

Pull Requests

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Guidelines

• Follow existing code style
• Update documentation for new features
• Test with real RustDesk clients
• Ensure backward compatibility

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Note: The HBBS patches maintain RustDesk's original AGPL-3.0 license. The web console and installation scripts are MIT licensed.

---

🙏 Credits

Open Source Components

• RustDesk: The amazing open-source remote desktop solution
• RustDesk Server: Original HBBS and HBBR servers
• Axum: Modern web framework for Rust
• Flask: Micro web framework for Python
• Material Icons: Google's Material Design icons
• Font Awesome: Icon inspiration (not used in final version)

Inspiration

• RustDesk's simple yet powerful architecture
• Modern web design trends (glassmorphism, neumorphism)
• NOC (Network Operations Center) monitoring dashboards

Special Thanks

• RustDesk development team for creating an excellent open-source alternative
• The Rust community for amazing tools and libraries
• Contributors and testers who helped improve this project

---

📞 Support

• Documentation: Check the docs/ folder
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• RustDesk Community: RustDesk Discord

---

🌐 Links

• GitHub: https://github.com/UNITRONIX/Rustdesk-FreeConsole
• RustDesk: https://rustdesk.com/
• RustDesk GitHub: https://github.com/rustdesk/rustdesk

---

📚 Documentation

Core Documentation

• README.md - This file (overview and installation)
• LICENSE - MIT License
• VERSION - Current version number

Additional Documentation (docs/)

• CHANGELOG.md - Complete version history
• CONTRIBUTING.md - How to contribute
• INSTALLATION_V1.4.0.md - Detailed installation guide
• UPDATE_GUIDE.md - Update instructions
• KEY_TROUBLESHOOTING.md - Key troubleshooting guide
• PORT_SECURITY.md - Port security information
• PROJECT_STRUCTURE.md - Project structure overview

Technical Documentation

• hbbs-patch/ - HBBS modification documentation
• dev_modules/ - Development and testing tools

---

Made with ❤️ by the community

If you find this project useful, please consider giving it a ⭐ on GitHub!

⬆ Back to Top