Installation
BetterDesk supports Linux (bare-metal), Windows (PowerShell), and Docker as primary install paths. FreeBSD is Tier 3 / community (manual build + example rc.d; no betterdesk.sh). Default Linux paths are /opt/betterdesk (Go server) and /opt/BetterDeskConsole (web panel); the installer still detects legacy /opt/rustdesk installs.
Requirements
Linux
- Ubuntu 20.04+ / Debian 11+ / CentOS 8+ / AlmaLinux 8+
- 1 CPU core, 512 MB RAM minimum (2 cores, 2 GB recommended)
- Root access (sudo)
- Open ports: 21114-21119 TCP, 21116 UDP, 5000 TCP (web console)
- Node.js 22+ (auto-installed by script; installer targets Node.js 22 LTS while the Node.js 24 native cleanup-hook regression is resolved)
- Existing bare-metal installations running Node.js 24.19.x should switch the console runtime to Node.js 22.x before restarting the service; the installer does not force-downgrade an existing Node installation.
Windows
- Windows 10/11 or Windows Server 2019+
- PowerShell 5.1+ (run as Administrator)
- NSSM (auto-installed by script)
- Open firewall ports: 21114-21119 TCP, 21116 UDP, 5000 TCP
Docker
- Docker Engine 20.10+ with Docker Compose v2
- 512 MB RAM minimum
FreeBSD (experimental / community)
- FreeBSD 13+ (amd64); root or doas/sudo
pkgpackages:git,go,node,npm,python3,ca_root_nss- Open ports (e.g. via
pf): TCP 21114-21119, 21121, 5000; UDP 21116 - No official installer or release binaries — see FreeBSD (experimental) below and
contrib/freebsd/
Linux Installation
Interactive Mode
git clone https://github.com/UNITRONIX/BetterDesk.git
cd BetterDesk
sudo ./betterdesk.sh
The interactive menu offers:
| Option | Description |
|---|---|
| 1 | New installation (full setup from scratch) |
| 2 | Update existing installation |
| 3 | Repair (auto-fix common issues) |
| 4 | Validate installation correctness |
| 5 | Create backup |
| 6 | Reset admin password |
| 7 | Build binaries from source |
| 8 | Run diagnostics |
| 9 | Uninstall |
| C | Configure SSL/TLS certificates |
| M | Migrate databases (SQLite ↔ PostgreSQL) |
Automatic Mode
sudo ./betterdesk.sh --auto
Non-interactive install with default settings. Useful for CI/CD or scripted deployments.
Options
# Skip SHA256 binary verification
sudo ./betterdesk.sh --skip-verify
# Custom API port
API_PORT=21120 sudo ./betterdesk.sh --auto
# Custom relay servers (overrides auto-detected IP)
RELAY_SERVERS=YOUR.PUBLIC.IP sudo ./betterdesk.sh --auto
Installation Path
After installation, files are located at:
| Path | Description |
|---|---|
/opt/betterdesk/ |
Go server binary, keys, database |
/opt/BetterDeskConsole/ |
Node.js web console |
/etc/systemd/system/betterdesk-server.service |
Go server systemd service |
/etc/systemd/system/betterdesk-console.service |
Node.js systemd service |
Verify Installation
sudo systemctl status betterdesk-server
sudo systemctl status betterdesk-console
# Check logs
journalctl -u betterdesk-server -f
journalctl -u betterdesk-console -f
Windows Installation
Interactive Mode
Open PowerShell as Administrator:
git clone https://github.com/UNITRONIX/BetterDesk.git
cd BetterDesk
.\betterdesk.ps1
Automatic Mode
.\betterdesk.ps1 -Auto
Options
# Skip SHA256 verification
.\betterdesk.ps1 -SkipVerify
# Custom RustDesk Client API port (default 21121; Go admin API is GO_API_PORT=21114)
$env:API_PORT = "21121"
.\betterdesk.ps1 -Auto
Installation Path
| Path | Description |
|---|---|
C:\BetterDesk\ |
Go server binary, keys, database |
C:\BetterDeskConsole\ |
Node.js web console |
Services are registered via NSSM and can be managed from services.msc.
Docker Installation
Quick Start (Pre-built Images)
curl -fsSL https://raw.githubusercontent.com/UNITRONIX/BetterDesk/main/docker-compose.quick.yml -o docker-compose.yml
docker compose up -d
Build Locally
git clone https://github.com/UNITRONIX/BetterDesk.git
cd BetterDesk
docker compose up -d --build
Interactive Docker Script
./betterdesk-docker.sh
See Docker for detailed Docker documentation.
FreeBSD (experimental)
FreeBSD is Tier 3 (community). There is no betterdesk.sh path (that installer assumes Linux + systemd). Build the Go server and Node panel from source, then optionally install the example rc.d scripts from the repository.
Quick outline
pkg install -y git go node npm python3 ca_root_nss
git clone https://github.com/UNITRONIX/BetterDesk.git
cd BetterDesk/betterdesk-server
CGO_ENABLED=0 go build -o betterdesk-server .
install -d /usr/local/betterdesk
install -m 755 betterdesk-server /usr/local/betterdesk/
# Place id_ed25519 / id_ed25519.pub under /usr/local/betterdesk
# Panel: copy web-nodejs → /usr/local/BetterDeskConsole, then:
cd /usr/local/BetterDeskConsole
npm ci --omit=dev
# Configure .env (RUSTDESK_DIR=/usr/local/betterdesk, etc.)
install -m 755 /path/to/BetterDesk/contrib/freebsd/rc.d/betterdesk_server \
/usr/local/etc/rc.d/betterdesk_server
install -m 755 /path/to/BetterDesk/contrib/freebsd/rc.d/betterdesk_console \
/usr/local/etc/rc.d/betterdesk_console
sysrc betterdesk_server_enable=YES
sysrc betterdesk_server_relay=YOUR.PUBLIC.IP
sysrc betterdesk_console_enable=YES
service betterdesk_server start
service betterdesk_console start
Full notes, path defaults, and limits (no panel updater FreeBSD binaries): see contrib/freebsd/README.md in the repo. Pull requests improving FreeBSD packaging are welcome (#310).
PostgreSQL Setup
By default, BetterDesk uses SQLite. To use PostgreSQL:
During Installation
When prompted for database type, choose PostgreSQL and provide the connection DSN:
postgres://user:password@host:5432/betterdesk?sslmode=disable
Migrate Existing Data
# Interactive
sudo ./betterdesk.sh
# Choose option M — Migrate databases
# Or use the migration tool directly
./tools/migrate/migrate-linux-amd64 -mode sqlite2pg \
-src /opt/betterdesk/db_v2.sqlite3 \
-dst "postgres://user:pass@localhost:5432/betterdesk"
See Migration for more details.
After Installation
- Open http://your-server:5000 in a browser
- Log in with the admin credentials displayed during installation
- Configure your Client Setup to connect to your server
- Optionally configure TLS/SSL certificates for encrypted connections
Upgrading
From Previous BetterDesk Version
# Linux
sudo ./betterdesk.sh
# Choose option 2 — Update
# Windows
.\betterdesk.ps1
# Choose option 2 — Update
The update process preserves:
- Database files (
db_v2.sqlite3; legacyauth.dbif still in use) - PostgreSQL configuration
- SSL certificates
- API keys
- Admin credentials
From RustDesk OSS Server
If you are migrating from the original RustDesk OSS server (hbbs+hbbr), the installer detects the legacy Rust server and recommends a fresh install. See Migration for data migration steps.
Uninstalling
# Linux
sudo ./betterdesk.sh
# Choose option 9 — Uninstall
# Windows
.\betterdesk.ps1
# Choose option 9 — Uninstall
This removes all services, binaries, and optionally data files.
Check it worked
# Linux services
sudo systemctl status betterdesk-server betterdesk-console
curl -s http://localhost:21114/api/health
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5000/
Expect health JSON and HTTP 200 (or a login redirect) from the panel. Then Client Setup.
See also
- Configuration — environment variables and service units
- Panel Updates — in-app updates via Settings → Updates
- Docker Deployment — container deployment
- Migration Guide — SQLite ↔ PostgreSQL, RustDesk OSS migration
- Privacy — what stays on your server
Start
Console
- Web Console
- User Management
- Organizations and RBAC
- LDAP / Active Directory
- OIDC SSO
- Client Generator
- Fleet and Policies
- Unattended Access and WoL
- Web Remote Desktop
- UX 3.5
Ops
Help
Advanced
- API Reference
- CDAP
- SDK
- Alpha Software Notice
- Desktop Clients
- MeshAgent
- Chat E2E Encryption
- Licensing
Source: docs/wiki/
Repository · Issues · Discussions · Releases · Privacy · Sponsors
Wiki source: docs/wiki/ — last sync: 2026-09-06