BetterDesk/docs/wiki/Desktop-Clients.md

Desktop Clients

BetterDesk provides two Tauri v2 desktop applications and a headless Go agent for different use cases.

Warning

The MGMT Client and Agent Client are in early alpha (v1.0.0-alpha) and are NOT production-ready. They are under active development, may contain bugs, incomplete features, and breaking changes between versions. Do not deploy these clients in production environments. For production use, rely on the Web Console (Node.js) for administration and the standard RustDesk client for remote desktop connections. See the Alpha Software Notice page for full details.

Component	Status	Production Use
Go Server	✅ Stable	✅ Recommended
Web Console (Node.js)	✅ Stable	✅ Recommended
Support Agent (Go/Wails)	✅ Active	✅ Recommended end-user agent
MGMT Client (Tauri)	⚠️ Alpha	❌ Do not use in production
Agent Client (Tauri)	⚠️ Alpha	❌ Do not use in production (Support Agent is preferred)
Native Agent (Go)	✅ Stable	Engine used by Support Agent

---

BetterDesk Support Agent

Purpose: Lightweight inbound-only end-user agent for remote support. Operators connect via Web Remote (CDAP) in the console — the Support Agent never initiates connections to other peers.

Technology: Single Go binary with Wails UI by default (Fyne UI optional via BETTERDESK_SUPPORT_FYNEUI=1), embedding the betterdesk-agent CDAP engine.

Features

Feature	Description
Your ID + access password	Stable per-machine ID; supervised accept or unattended password
Web Remote desktop	CDAP session (keyboard/mouse, quality presets)
File transfer	Bidirectional via Web Remote file modal (CDAP /files channel)
Chat	Operator ↔ end-user chat in Web Remote
Remote audio	CDAP audio stream in unified /remote viewer
Lock / restart	Operator toolbar actions relayed to the agent
Branding	Appearance + server endpoints baked at Generator build time
Enrollment	Per-device register; unique device_token after approval (managed mode)
Artifacts	Windows portable .exe / .msi; Linux portable, AppImage, .deb, .rpm

Build & deploy

1. Console → Generator → New Support Agent bundle
2. Set branding, server host, optional unattended
3. Wait for platform builds (toolchain status shown in the editor)
4. Share the public hub link /d/:slug
5. After panel updates that change agent source, bundles are requeued automatically

See also betterdesk-support-agent/README.md.

---

BetterDesk MGMT Client

⚠️ Alpha — not production-ready. See Alpha Software Notice for known limitations.

Purpose: Operator/Admin desktop application for managing devices and conducting remote sessions.

Technology: Tauri v2 + SolidJS frontend + Rust backend (~40K LOC, 25+ modules, 100+ IPC commands)

Features

Feature	Description
Operator login	JWT-based auth with TOTP 2FA support
Device list	Live status, search, filter, group by tags
Remote desktop	H.264/VP9 video decode, multi-monitor, session recording
Input forwarding	Keyboard (40+ keys, F1-F12, modifiers), mouse, text
File transfer	Local file browser, drag-and-drop transfer
Chat	E2E encrypted operator ↔ end-user messaging
Wake-on-LAN	Send WOL packets to offline devices
Server management	Health, clients, operators, audit, API keys, config
Notification center	Real-time push with type filtering
Help requests	Inbox with accept & connect workflow
Session history	Audit trail of past connections
Unattended access	Configure device passwords and access schedules
Activity tracking	500-entry ring buffer with action icons
mDNS discovery	LAN server discovery via multicast DNS

Installation

Download from the Releases page:

• Windows (NSIS): BetterDesk_MGMT_1.0.0_x64-setup.exe
• Windows (MSI): BetterDesk_MGMT_1.0.0_x64_en-US.msi

Building from Source

cd betterdesk-mgmt
npm install
cd src-tauri
cargo tauri build

Requirements: Rust 1.70+, Node.js 22+, WebView2 (Windows), webkit2gtk (Linux)

Configuration

On first launch, enter your BetterDesk server address. The client connects to:

• Port 5000 — Web console (for operator login)
• Port 21114 — Go server API (for device management)
• Port 21117 — Relay server (for remote sessions)

---

BetterDesk Agent Client

⚠️ Alpha — not production-ready. See Alpha Software Notice for known limitations.

Purpose: Lightweight endpoint agent installed on managed devices. Provides the end-user interface for help requests and remote assistance.

Technology: Tauri v2 + SolidJS frontend + Rust backend (4 modules, 17 IPC commands)

Features

Feature	Description
Setup wizard	5-step server onboarding with validation
Device registration	Machine UID-based device ID (BD-{hash})
System info	Hostname, OS, CPU, RAM, disk collection
Status panel	Connection status, device ID, copy button
Chat	Operator ↔ end-user chat panel
Help requests	4-state flow: compose → sending → sent → confirmed
Settings	Connection, privacy, general, about tabs
Tray icon	Minimize to system tray, show/quit menu
Autostart	Launch on system boot
Single instance	Windows mutex prevents duplicate processes

Installation

Download from the Releases page:

• Windows (NSIS): BetterDesk_Agent_1.0.0_x64-setup.exe

Setup Flow

1. Install and launch the agent
2. Enter your BetterDesk server address
3. The agent validates:
   • Server availability
   • Protocol compatibility
   • Registration open
   • Certificate verification
4. Device registers via heartbeat API
5. System info syncs via sysinfo API
6. Device appears in the web console

Building from Source

cd betterdesk-agent-client
npm install
cd src-tauri
cargo tauri build

---

BetterDesk Native Agent (Go)

Purpose: Headless agent for servers, IoT devices, and headless systems. Implements the CDAP protocol for telemetry, remote commands, and file management.

Technology: Go binary (~750 LOC core, gopsutil for metrics)

Features

Feature	Description
CDAP WebSocket	Connects to Go server on port 21122
System metrics	CPU, memory, disk usage (1s sample rate)
9 default widgets	3 gauges, 2 text, terminal, file browser, button, clipboard
Terminal emulation	PTY on Unix, cmd.exe on Windows
File browser	List, read, write, delete with path traversal protection
Clipboard	Cross-platform via OS commands (xclip/pbcopy/powershell)
Screenshot	Platform-specific capture (screencapture/import/scrot)
Heartbeat	Configurable interval (default 15s)
Auto-reconnect	Configurable delay (default 5s)

Installation

# Linux
cd betterdesk-agent
go build -o betterdesk-agent .
sudo ./install/install.sh

# Windows
cd betterdesk-agent
go build -o betterdesk-agent.exe .
.\install\install.ps1

Configuration

Create config.json:

{
  "server": "ws://your-server:21122/cdap",
  "auth_method": "api_key",
  "api_key": "your-cdap-api-key",
  "device_id": "",
  "device_name": "Production Server",
  "device_type": "os_agent",
  "tags": ["production", "linux"],
  "terminal": true,
  "file_browser": true,
  "clipboard": true,
  "screenshot": true,
  "file_root": "/",
  "heartbeat_sec": 15,
  "reconnect_sec": 5,
  "log_level": "info"
}

CLI Flags

betterdesk-agent [flags]

  -server string     WebSocket server URL (overrides config)
  -auth string       Auth method: api_key, device_token, user_password
  -api-key string    API key for authentication
  -device-id string  Device ID (auto-generated if empty)
  -device-name string  Human-readable device name
  -device-type string  Device type (default "os_agent")
  -config string     Config file path (default "config.json")
  -terminal          Enable terminal access
  -file-browser      Enable file browser
  -clipboard         Enable clipboard access
  -screenshot        Enable screenshot capture
  -heartbeat int     Heartbeat interval in seconds (default 15)
  -reconnect int     Reconnect delay in seconds (default 5)

Security

The native agent runs with hardened systemd settings:

• ProtectSystem=strict (read-only filesystem)
• PrivateTmp=yes (isolated /tmp)
• NoNewPrivileges=yes (no privilege escalation)

See CDAP for the full protocol specification and SDK documentation.

---

Comparison

Feature	MGMT Client	Agent Client	Native Agent
Purpose	Admin/Operator	End User	Server/IoT
UI	Full desktop app	Minimal status panel	Headless (no UI)
Platform	Windows, Linux, macOS	Windows, Linux, macOS	Any (Go binary)
Protocol	REST API + Relay	REST API	CDAP WebSocket
Remote Desktop	✅ H.264/VP9	Receives connections	Via CDAP
File Transfer	✅ Drag-and-drop	Via operator	✅ File browser
Chat	✅ Operator side	✅ User side	❌
Terminal	❌	❌	✅ PTY
Metrics	Views metrics	Reports metrics	Reports metrics
Single Instance	✅ Mutex	✅ Mutex	✅ PID file
Tray Icon	✅	✅	❌
Binary Size	~4 MB (MSI)	~3 MB (NSIS)	~10 MB (Go)

---

See also

• ⚠️ Alpha Notice — MGMT/Agent limitations
• CDAP — Native Go agent protocol
• Web Console — recommended admin UI