🚀 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

• Overview
• Features
• Screenshots
• Architecture
• Installation
  • Automatic Installation
  • Manual Installation
  • 🔑 Key Protection
• Troubleshooting
• Configuration
• API Documentation
• Development
• Technology Stack
• Contributing
• License
• Credits

---

🌟 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 (NEW!)

• 🚀 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 detailed information.

�🛡️ 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

---

📸 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    │
│   (Flask on Port 5000)      │
│   • Dashboard               │
│   • Device Management       │
│   • Statistics              │
└─────────────────────────────┘

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: Flask application with modern UI
5. SQLite Database: Original RustDesk database (unchanged)

---

🚀 Installation

Prerequisites

• Linux: Ubuntu 20.04+, Debian 11+, CentOS 8+
• Windows: Windows 10+, Windows Server 2016+
• RustDesk: Fresh RustDesk installation OR existing working HBBS (script auto-detects)
• Linux Dependencies: python3, pip3, curl, systemd
• Windows Dependencies: Python 3.8+, PowerShell 5.1+
• No Compilation Required: Uses precompiled binaries

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

� Docker Installation

For Docker users, we provide a comprehensive Docker setup:

# Clone the repository
git clone https://github.com/UNITRONIX/Rustdesk-FreeConsole.git
cd Rustdesk-FreeConsole

# Quick setup (recommended)
chmod +x docker-quickstart.sh
./docker-quickstart.sh

# OR: Custom installation with path selection
chmod +x install-docker.sh
sudo ./install-docker.sh

Docker installation features:

• ✅ Works with existing RustDesk Docker containers
• ✅ Custom path selection for RustDesk data
• ✅ Volume mounting support
• ✅ Container or host installation modes
• ✅ Automatic binary deployment
• ✅ Database migration included
• ✅ Complete docker-compose setup
• ✅ Nginx reverse proxy (optional)

Full Docker guide: DOCKER_SUPPORT.md

�🐧 Linux Installation

Enhanced installer with Docker support and custom path detection:

# Clone the repository
git clone https://github.com/UNITRONIX/Rustdesk-FreeConsole.git
cd Rustdesk-FreeConsole

# Make the installer executable
chmod +x install-improved.sh

# Run as root (creates backup automatically)
sudo ./install-improved.sh

Features:

• ✅ Automatic Docker/containerized environment detection
• ✅ Custom RustDesk path detection (searches /opt, /usr/local, /home)
• ✅ --break-system-packages support for Debian 3.11+
• ✅ File validation and verification
• ✅ 🔑 Encryption key protection - preserves existing keys
• ✅ Dynamic .pub file scanning - works with any public key filename
• ✅ Multiple backup options - automatic, manual, or existing backup
• ✅ Key regeneration with warnings - prevents accidental key changes
• ✅ API key generation - automatic X-API-Key authentication setup
• ✅ LAN access configuration - web console and API accessible on network

🔄 Updating Existing Installation

If you already have BetterDesk Console installed and want to upgrade to v1.5.0:

cd Rustdesk-FreeConsole

# Make the update script executable
chmod +x update-to-v1.5.0.sh

# Run as root
sudo ./update-to-v1.5.0.sh

Update features:

• ✅ Automatic backup before changes
• ✅ Database migration (adds last_online, is_deleted columns)
• ✅ Authentication tables creation
• ✅ API key generation and configuration
• ✅ Preserves existing configuration
• ✅ Creates default admin user (if needed)
• ✅ Updates HBBS/HBBR binaries
• ✅ Rollback capability if update fails

🐳 Docker Installation & Update

For users running RustDesk in Docker containers:

# Docker installation/update with path selection
chmod +x install-docker.sh
sudo ./install-docker.sh

# Quick Docker setup (new installations)
chmod +x docker-quickstart.sh
./docker-quickstart.sh

Docker installer features:

• ✅ Detects existing RustDesk containers
• ✅ Custom path selection for Docker volumes
• ✅ Works with mounted volumes or inside containers
• ✅ Automatic binary deployment
• ✅ Database migration support
• ✅ Full docker-compose configuration

Quick Database Fix (if devices show as offline)

If devices appear offline even though they're connected, run the database migration:

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

# Restart services
sudo systemctl restart hbbs betterdesk

🪟 Windows Installation

Enhanced installer with automatic path detection:

# Clone the repository
git clone https://github.com/UNITRONIX/Rustdesk-FreeConsole.git
cd Rustdesk-FreeConsole

# Run as Administrator
.\install-improved.ps1

Features:

• ✅ Automatic RustDesk installation detection
• ✅ Multiple installation path support
• ✅ File validation and verification
• ✅ Windows service configuration

⚠️ Important: Platform-Specific Binaries

The installers automatically use the correct binaries for your platform:

• Linux: Uses hbbs-patch/bin-with-api/hbbs-v8-api (Linux ELF binary)
• Windows: Uses hbbs-patch/bin-with-api/hbbs-v8-api.exe (Windows PE binary)

Do not mix binaries between platforms! Each installer is designed to work only on its respective operating system.

🔑 Key Protection (IMPORTANT!)

v1.5.0+ includes comprehensive encryption key protection:

⚠️ 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 v1.5.0+ automatically:

• ✅ Detects existing encryption keys
• ✅ Scans for ANY .pub file (not just id_ed25519.pub)
• ✅ Offers multiple backup options (automatic, manual, existing)
• ✅ Warns before any key changes
• ✅ Never regenerates keys without explicit confirmation

During installation, you'll see:

🔑 EXISTING ENCRYPTION KEYS DETECTED 🔑
Found: id_ed25519.pub

Options:
  1) Keep existing keys (RECOMMENDED)
  2) Regenerate keys (⚠️ BREAKS client connections)
  3) Show key information

Always choose Option 1 unless you know what you're doing!

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

What's New in v1.5.0 (Latest)

• 🔐 Authentication System: User login with bcrypt password hashing
• 👥 Role-Based Access Control: Admin, Operator, and Viewer roles
• 🌐 Sidebar Navigation: Modern UI with 5 main sections
• 🔑 Password-Protected Public Key: Requires verification to view
• ⚙️ Settings Page: Change password functionality with token regeneration
• 👤 User Management: Admin panel to create, edit, delete users
• 📝 Extended About Page: Open source credits and license info
• 🛡️ CSRF Protection: Flask-WTF security
• ⏱️ Rate Limiting: 5 login attempts per minute

🔒 Manual Installation on SSH Server (Security Update)

If you compiled new binaries with security fixes on your SSH server:

# Upload the manual installation script
scp hbbs-patch/MANUAL_INSTALL.sh your-user@your-server:~/

# SSH to server and run
ssh your-user@your-server
sudo bash ~/MANUAL_INSTALL.sh

The script will:

1. Stop HBBS/HBBR services
2. Backup old binaries (timestamped)
3. Install new binaries from ~/build/hbbs-patch/rustdesk-server/target/release/
4. Restart services
5. Verify API is responding on port 21120

🔄 Container Updates & Security

Important: Watchtower has been removed from docker-compose.yml as it's no longer maintained (security risk).

Secure update methods:

# Manual updates (recommended)
docker-compose pull
docker-compose down
docker-compose up -d

# Check for updates weekly
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.CreatedAt}}"

# Alternative: Use modern tools
# - GitHub Dependabot (automatic PRs)
# - Renovate Bot (automatic updates) 
# - Custom update scripts with notifications

---

🔧 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:

cd /path/to/Rustdesk-FreeConsole
sudo bash repair-keys.sh
# Select option 5: Restore from backup

If BetterDesk broke your setup:

# 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

🔧 Using the Repair Tool

The repair-keys.sh tool can fix most key-related issues:

sudo bash repair-keys.sh

Available options:

1. 📋 Show current key information
2. 🔐 Verify and fix key permissions
3. 📤 Export public key
4. 🔄 Regenerate keys (⚠️ BREAKS connections)
5. 💾 Restore keys from backup

🐳 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 BetterDesk console starts but doesn't show default admin credentials in logs.

Cause: Database migration script doesn't run automatically in Docker container.

Choose Your Solution (3 options available):

---

🚀 Option 1: One-Click Fix Script (Easiest)

For Linux/macOS:

# Make script executable and run
chmod +x fix-admin.sh
./fix-admin.sh

For Windows:

# Run the batch file
fix-admin.bat

What it does:

• ✅ Automatically detects your Docker setup
• ✅ Creates admin account if missing
• ✅ Shows credentials clearly
• ✅ Works with existing installations

---

⚙️ Option 2: Custom Admin Credentials (Recommended)

Set your own admin password by editing docker-compose.yml:

# In docker-compose.yml, under betterdesk-console service:
environment:
  # Add these lines (uncomment and customize):
  - ADMIN_USERNAME=admin
  - ADMIN_PASSWORD=YourSecurePassword123

Steps:

1. Edit docker-compose.yml with your credentials
2. Restart: docker compose down && docker compose up -d
3. Login with your chosen credentials

Benefits:

• 🔒 You control the password
• 🔄 Survives container restarts
• 📝 No need to save random passwords

---

🤖 Option 3: Automatic Migration (Advanced)

Use the improved Dockerfile that auto-creates admin on first startup:

# 1. Update to latest files
git pull

# 2. Rebuild with automatic migration
docker compose down
docker compose build betterdesk-console
docker compose up -d

# 3. Check logs for generated credentials
docker compose logs betterdesk-console | grep -A5 "DEFAULT ADMIN CREDENTIALS"

Features:

• ✅ Zero configuration needed
• ✅ Runs migration automatically
• ✅ Shows credentials in logs
• ✅ Saves backup to /app/data/admin_credentials.txt

---

🛠️ Manual Option (Fallback)

If the above options don't work, run the migration manually:

🛠️ Manual Option (Fallback)

If the above options don't work, run the migration manually:

# Run migration manually 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 or use repair tool
Wrong key in WebConsole	Multiple .pub files	Remove incorrect files or upgrade to v9+
Services won't start	Permission issues	Run sudo bash repair-keys.sh → option 2
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	Binaries not updated	Copy binaries from hbbs-patch/bin-with-api/
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)

🚨 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.

Solution:

# Copy new binary
sudo cp hbbs-patch/bin-with-api/hbbs-v8-api /opt/rustdesk/
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/hbbs.service
sudo systemctl daemon-reload
sudo systemctl restart hbbs

4. Update Script Cannot Find Installation

Symptoms: update-to-v1.5.0.sh reports "Installation directory not found"

Cause: Non-standard installation path.

Solution:

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

# Run migration manually pointing to correct paths
python3 migrations/v1.5.0_fix_online_status.py /path/to/db_v2.sqlite3

📞 Getting Help

Before asking for help:

1. Check the troubleshooting guides above
2. Try the repair tool: sudo bash repair-keys.sh
3. Collect diagnostics:

   sudo journalctl -u rustdesksignal -n 50 > ~/rustdesk_logs.txt
   ls -lah /opt/rustdesk/*.pub >> ~/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

To change, edit /opt/BetterDeskConsole/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 (if needed for external tools)
sudo ufw allow from 192.168.0.0/16 to any port 21114 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
├── install.sh                   # Automatic installer
├── screenshots/                 # UI screenshots
│   ├── dashboard.png
│   ├── devices-list.png
│   ├── device-details.png
│   ├── public_key_page.png
│   ├── settings_page.png
│   ├── user_mgmt.png
│   └── about.png
├── web/                         # Web console
│   ├── app.py                   # Flask application
│   ├── app_demo.py              # Demo with mock data
│   ├── requirements.txt         # Python dependencies
│   ├── betterdesk.service       # Systemd service file
│   ├── templates/
│   │   └── index.html           # Main HTML template
│   └── static/
│       ├── style.css            # Glassmorphism CSS
│       ├── script.js            # Frontend JavaScript
│       └── material-icons.woff2 # Material Icons font
└── hbbs-patch/                  # HBBS modifications
    ├── README.md                # Patch documentation
    └── src/
        ├── http_api.rs          # HTTP API server (NEW)
        ├── main.rs              # Modified entry point
        ├── peer.rs              # Modified PeerMap
        └── rendezvous_server.rs # Modified server logic

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
• Flask: Python web framework
• SQLite: Database (RustDesk original)

Frontend

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

DevOps

• Systemd: Service management
• Bash: 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

---

🗺️ Roadmap

Known Limitations (v1.0.0)

• Device ID Modification: Changing device IDs is not recommended and may cause access issues
  • Workaround: Use the Note field to assign custom names/labels
• Device Deletion: Delete functionality is currently unstable
  • Status: Under investigation, fix planned for v1.0.1
• No Authentication: Web console has no user authentication (suitable for internal networks only)

Version 1.0.1 (Bug Fixes - In Progress)

• Fix device deletion functionality
• Improve device ID change handling
• Add confirmation dialogs for destructive operations
• Better error messages for failed operations

Version 1.1 (Planned)

• Multi-language support (i18n)
• User authentication system
• Role-based access control (RBAC)
• Connection history logs
• Performance metrics dashboard

Version 1.2 (Future)

• Mobile app (React Native)
• WebSocket for real-time updates
• Device grouping and tagging
• Scheduled maintenance windows
• Email/Slack notifications
• REST API authentication (JWT)

Version 2.0 (Vision)

• Multi-server support
• High availability (HA) setup
• Advanced analytics
• Custom themes
• Plugin system

---

🌐 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