CrossDesk Self-Hosted Remote Desktop: Complete Setup Guide with Docker & SSL

Looking for a lightweight and reliable remote desktop software? CrossDesk might be just what you need. Built on the MiniRTC real-time audio-video transmission library, its biggest advantage is complete self-hosting capability, keeping your data under your control.

What is CrossDesk?

CrossDesk is essentially an experimental application of the MiniRTC library. MiniRTC is quite impressive - it integrates network traversal (RFC5245), H264/AV1 video encoding/decoding, Opus audio encoding/decoding, signaling interaction, network congestion control, SRTP transmission encryption, and a bunch of other core features. CrossDesk packages these capabilities into a user-friendly remote desktop tool.

Core Features

🪶 Lightweight Design: Built on the efficient MiniRTC library with minimal resource usage
🌐 Cross-Platform Support: Supports Windows, Linux, macOS, and other mainstream operating systems
🔒 Self-Hosted Service: Fully controllable private deployment with guaranteed data security
⚡ High-Performance Transmission: Supports H264/AV1 video encoding and Opus audio encoding
🛡️ Secure Encryption: Built-in SRTP transmission encryption and certificate authentication
🎛️ Simple to Use: Quick remote connections via peer ID

Important Resources

💻 GitHub Repository: https://github.com/kunkundi/crossdesk
📦 Latest Release: https://github.com/kunkundi/crossdesk/releases/tag/v1.0.1
📖 Project Documentation: https://github.com/kunkundi/crossdesk/blob/self-hosted-server/README.md
🐛 Issue Reporting: https://github.com/kunkundi/crossdesk/issues

Quick Start

Download Pre-compiled Versions (Recommended)

Don’t want to deal with compilation? Just download the ready-to-use versions:

Windows Users

# Download Windows version
curl -L -o crossdesk-win-x64-1.0.1.exe https://github.com/kunkundi/crossdesk/releases/download/v1.0.1/crossdesk-win-x64-1.0.1.exe

# Run directly
./crossdesk-win-x64-1.0.1.exe

Linux Users

# Download Linux AMD64 version (.deb package)
wget https://github.com/kunkundi/crossdesk/releases/download/v1.0.1/crossdesk-linux-amd64-1.0.1.deb

# Install deb package
sudo dpkg -i crossdesk-linux-amd64-1.0.1.deb

# Or download ARM64 version
# wget https://github.com/kunkundi/crossdesk/releases/download/v1.0.1/crossdesk-linux-arm64-1.0.1.deb
# sudo dpkg -i crossdesk-linux-arm64-1.0.1.deb

macOS Users

# Download macOS ARM64 version (Apple Silicon)
curl -L -o crossdesk-macos-arm64-1.0.1.pkg https://github.com/kunkundi/crossdesk/releases/download/v1.0.1/crossdesk-macos-arm64-1.0.1.pkg

# Or download x64 version (Intel)
# curl -L -o crossdesk-macos-x64-1.0.1.pkg https://github.com/kunkundi/crossdesk/releases/download/v1.0.1/crossdesk-macos-x64-1.0.1.pkg

# Install pkg package
sudo installer -pkg crossdesk-macos-arm64-1.0.1.pkg -target /

First-Time Setup

Launch CrossDesk: Run the downloaded executable file
Get Device ID: The application will display your device’s ID after startup
Establish Connection: Enter the target device’s ID on another device to connect
Set Password (Optional): Configure password protection in settings

💡 Tip: If you need self-hosted servers or want to compile from source, continue reading the detailed sections below.

Basic Usage

CrossDesk is quite simple to use - basically a three-step process:

Connect to Remote Desktop: Find “Peer ID” in the menu bar, enter the target device ID, and click ”→” to connect
Password Protection: If the remote device has a password set, remember to enter the correct password for successful connection
Personalized Settings: Before connecting, you can adjust language, video encoding, and other preferences in settings

CrossDesk Interface

Compiling from Source

Want to compile it yourself? It’s not too difficult, just need to prepare some tools.

Required Dependencies

xmake: Main build tool
cmake: Auxiliary build system

Linux System Dependencies

Ubuntu/Debian users need to install these packages first (quite a few, but all necessary):

sudo apt-get install -y software-properties-common git curl unzip build-essential \
    libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev \
    libxcb-randr0-dev libxcb-xtest0-dev libxcb-xinerama0-dev libxcb-shape0-dev \
    libxcb-xkb-dev libxcb-xfixes0-dev libxv-dev libxtst-dev libasound2-dev \
    libsndio-dev libxcb-shm0-dev libpulse-dev

Installing Xmake Build Tool

CrossDesk uses Xmake for building, so you need to install it first:

Linux/macOS Installation

Using curl:

curl -fsSL https://xmake.io/shget.text | bash

Using wget:

wget https://xmake.io/shget.text -O - | bash

Windows Installation

Using PowerShell:

irm https://xmake.io/psget.text | iex

Compiling CrossDesk

1. Get Source Code

# Clone repository
git clone https://github.com/kunkundi/crossdesk.git
cd crossdesk

# Initialize submodules
git submodule init
git submodule update

2. Compile Project

# Compile CrossDesk
xmake b -vy crossdesk

3. Run Program

# Run CrossDesk
xmake r crossdesk

What if You Don’t Have CUDA Environment?

Linux Developers

No CUDA installed? No worries, CrossDesk provides a pre-configured Ubuntu 22.04 Docker image with everything you need, ready to use.

After entering the container, download the code and run:

export CUDA_PATH=/usr/local/cuda
export XMAKE_GLOBALDIR=/data
xmake b --root -vy crossdesk

Windows Developers

Windows users can install CUDA the same way:

# Install CUDA 12.6.3
xmake require -vy "cuda 12.6.3"

# Check installation info
xmake require --info "cuda 12.6.3"

Get the CUDA installation directory (installdir) from the output and add CUDA_PATH to system environment variables:

set CUDA_PATH=path_to_cuda_installdir

Then recompile:

xmake b -vy crossdesk

Xmake Compilation Options

Switching Build Modes

# Switch to debug mode
xmake f -m debug

# Switch to release mode
xmake f -m release

Compilation Parameters

# Optional compilation parameters
# -r : Rebuild target
# -v : Show detailed build logs
# -y : Auto-confirm prompts

# Example: Verbose mode compilation
xmake b -vy crossdesk

Runtime Options

# Run in debug mode
xmake r -d crossdesk

For more usage, refer to the Xmake Official Documentation.

Self-Hosted Server Deployment

Want to set up your own server? Docker is the easiest way.

Docker Deployment (Recommended)

Deploy CrossDesk server with the following command:

sudo docker run -d \
  --name crossdesk_server \
  --network host \
  -e EXTERNAL_IP=xxx.xxx.xxx.xxx \
  -e INTERNAL_IP=xxx.xxx.xxx.xxx \
  -e CROSSDESK_SERVER_PORT=9099 \
  -v /path/to/your/certs:/crossdesk-server/certs \
  -v /path/to/your/db:/crossdesk-server/db \
  -v /path/to/your/logs:/crossdesk-server/logs \
  crossdesk/crossdesk-server:latest

Parameter Description

Key parameters you need to configure:

EXTERNAL_IP: Server public IP, corresponding to the server address in CrossDesk client’s self-hosted server configuration
INTERNAL_IP: Server internal IP
CROSSDESK_SERVER_PORT: Port used by self-hosted service, corresponding to the server port in CrossDesk client’s self-hosted server configuration
/path/to/your/certs: Certificate file directory (must be created beforehand)
/path/to/your/db: CrossDesk Server device management database directory
/path/to/your/logs: Log file directory

Network Port Requirements

The server needs to open the following ports:

3478/udp and 3478/tcp: STUN/TURN service ports
30000-60000/udp: Media transmission port range
CROSSDESK_SERVER_PORT/tcp: CrossDesk service port (e.g., 9099 in the example)
443/tcp: HTTPS port

Firewall Configuration Example

# Ubuntu/Debian systems using ufw
sudo ufw allow 3478/udp
sudo ufw allow 3478/tcp
sudo ufw allow 30000:60000/udp
sudo ufw allow 9099/tcp
sudo ufw allow 443/tcp

# CentOS/RHEL systems using firewalld
sudo firewall-cmd --permanent --add-port=3478/udp
sudo firewall-cmd --permanent --add-port=3478/tcp
sudo firewall-cmd --permanent --add-port=30000-60000/udp
sudo firewall-cmd --permanent --add-port=9099/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload

Deployment Notes

Common pitfalls to avoid:

Directory Permissions: Those mounted directories (/path/to/your/) must be created first, or the container won’t start
Path Replacement: Don’t forget to replace /path/to/your/ in the examples with your actual paths
IP Configuration: Make sure EXTERNAL_IP and INTERNAL_IP are configured correctly
Port Conflicts: Ensure the specified ports aren’t occupied by other programs

Certificate Configuration

CrossDesk requires certificates for security. Clients need root certificate files, and servers need private keys and server certificate files.

Using Existing SSL Certificates

Have existing SSL certificates? Just use them directly - you can skip the certificate generation steps below.

Generate Your Own Certificates

No certificates? No problem, use this script to generate them automatically:

1. Create Certificate Generation Script

# Create certificate generation script
vim generate_certs.sh

2. Script Content

Copy the following content into the script:

#!/bin/bash
set -e

# Check parameters
if [ "$#" -ne 1 ]; then
    echo "Usage: $0 <SERVER_IP>"
    exit 1
fi

SERVER_IP="$1"

# File name definitions
ROOT_KEY="crossdesk.cn_root.key"
ROOT_CERT="crossdesk.cn_root.crt"
SERVER_KEY="crossdesk.cn.key"
SERVER_CSR="crossdesk.cn.csr"
SERVER_CERT="crossdesk.cn_bundle.crt"
FULLCHAIN_CERT="crossdesk.cn_fullchain.crt"

# Certificate subject information
SUBJ="/C=CN/ST=Zhejiang/L=Hangzhou/O=CrossDesk/OU=CrossDesk/CN=$SERVER_IP"

# 1. Generate root certificate private key
echo "Generating root certificate private key..."
openssl genrsa -out "$ROOT_KEY" 4096

# 2. Generate self-signed root certificate
echo "Generating self-signed root certificate..."
openssl req -x509 -new -nodes -key "$ROOT_KEY" -sha256 -days 3650 -out "$ROOT_CERT" -subj "$SUBJ"

# 3. Generate server private key
echo "Generating server private key..."
openssl genrsa -out "$SERVER_KEY" 2048

# 4. Generate server certificate signing request
echo "Generating server CSR..."
openssl req -new -key "$SERVER_KEY" -out "$SERVER_CSR" -subj "$SUBJ"

# 5. Create temporary OpenSSL config file with SAN extension
SAN_CONF="san.cnf"
cat > $SAN_CONF <<EOL
[ req ]
default_bits = 2048
distinguished_name = req_distinguished_name
req_extensions = req_ext
prompt = no

[ req_distinguished_name ]
C = CN
ST = Zhejiang
L = Hangzhou
O = CrossDesk
OU = CrossDesk
CN = $SERVER_IP

[ req_ext ]
subjectAltName = IP:$SERVER_IP
EOL

# 6. Sign server certificate with root certificate
echo "Signing server certificate..."
openssl x509 -req -in "$SERVER_CSR" -CA "$ROOT_CERT" -CAkey "$ROOT_KEY" -CAcreateserial \
    -out "$SERVER_CERT" -days 3650 -sha256 -extfile "$SAN_CONF" -extensions req_ext

# 7. Generate full certificate chain
cat "$SERVER_CERT" "$ROOT_CERT" > "$FULLCHAIN_CERT"

# 8. Clean up temporary files
rm -f "$ROOT_CERT.srl" "$SAN_CONF" "$ROOT_KEY" "$SERVER_CSR" "$FULLCHAIN_CERT"

echo "Certificate generation complete! Deployment files:"
echo "  Client root certificate: $ROOT_CERT"
echo "  Server private key: $SERVER_KEY"
echo "  Server certificate: $SERVER_CERT"

3. Execute Certificate Generation

# Add execution permissions
chmod +x generate_certs.sh

# Generate certificates (replace with your server's public IP)
./generate_certs.sh 111.111.111.111

Certificate File Description

The generated files serve different purposes:

crossdesk.cn_root.crt: Client root certificate
crossdesk.cn.key: Server private key (keep it secret)
crossdesk.cn_bundle.crt: Server certificate

Certificate Deployment

Place the generated certificate files in the server’s certificate directory:

# Create certificate directory
sudo mkdir -p /opt/crossdesk/certs

# Copy certificate files
sudo cp crossdesk.cn.key /opt/crossdesk/certs/
sudo cp crossdesk.cn_bundle.crt /opt/crossdesk/certs/
sudo cp crossdesk.cn_root.crt /opt/crossdesk/certs/

# Set appropriate permissions
sudo chmod 600 /opt/crossdesk/certs/crossdesk.cn.key
sudo chmod 644 /opt/crossdesk/certs/crossdesk.cn_bundle.crt
sudo chmod 644 /opt/crossdesk/certs/crossdesk.cn_root.crt

Client Configuration

Installing Client Certificates

If the client status bar shows “Server not connected” at runtime, you need to install client certificates first:

Official Client Installation: First download and install the client from the CrossDesk Official Website to install the required certificate files in your environment
Manual Certificate Installation: Import the generated crossdesk.cn_root.crt root certificate file into the client system’s certificate store

Self-Hosted Server Configuration

Configure the self-hosted server in the CrossDesk client:

Open CrossDesk client
Go to Settings → Self-Hosted Server Configuration
Fill in server address: Your server’s public IP
Fill in server port: The configured CROSSDESK_SERVER_PORT (e.g., 9099)
Import root certificate file: crossdesk.cn_root.crt

Troubleshooting

Common Issues

1. Client Shows “Server Not Connected”

Solutions:

Ensure client certificates are properly installed
Check if server IP and port configuration are correct
Verify firewall settings and ensure relevant ports are open

2. Docker Container Startup Failure

Troubleshooting Steps:

# View container logs
sudo docker logs crossdesk_server

# Check if mounted directories exist
ls -la /path/to/your/certs
ls -la /path/to/your/db
ls -la /path/to/your/logs

# Create missing directories
sudo mkdir -p /path/to/your/{certs,db,logs}

3. Compilation Failure

Common Causes and Solutions:

# Check xmake version
xmake --version

# Update xmake
xmake update

# Clean build cache
xmake clean

# Recompile
xmake b -vy crossdesk

4. Network Connection Issues

Diagnostic Steps:

# Check port listening status
netstat -tulpn | grep 9099

# Test port connectivity
telnet your-server-ip 9099

# Check firewall status
sudo ufw status  # Ubuntu
sudo firewall-cmd --list-all  # CentOS

Log Analysis

View Server Logs

# View Docker deployment logs
sudo docker logs -f crossdesk_server

# View mounted log files
tail -f /path/to/your/logs/crossdesk-server.log

Client Debugging

# Run client in debug mode
xmake r -d crossdesk

Performance Optimization Recommendations

Server-Side Optimization

Resource Configuration:
- Ensure server has sufficient CPU and memory resources
- Use SSD storage to improve I/O performance
Network Optimization:
- Choose low-latency network environments
- Consider using CDN acceleration (if you have users in multiple geographic locations)
System Tuning:

# Adjust network parameters
echo 'net.core.rmem_max = 16777216' >> /etc/sysctl.conf
echo 'net.core.wmem_max = 16777216' >> /etc/sysctl.conf
sysctl -p

Client Optimization

Encoding Settings: Choose appropriate video encoding formats (H264/AV1) based on network bandwidth
Resolution Adjustment: Lower resolution in poor network conditions
Network Environment: Prefer wired network connections

Security Best Practices

Network Security

Use VPN: Recommend accessing self-hosted servers through VPN
IP Whitelist: Configure IP whitelists in firewall to restrict access
Regular Updates: Keep system and Docker images up to date

Certificate Management

Regular Renewal: Recommend renewing certificates annually
Secure Storage: Properly safeguard private key files with appropriate file permissions
Certificate Backup: Regularly backup certificate files to secure locations

FAQ

For more detailed frequently asked questions and solutions, please refer to the CrossDesk FAQ Documentation.

Summary

CrossDesk, as a lightweight remote desktop solution based on MiniRTC, provides users with:

🪶 Lightweight and Efficient: Built on the optimized MiniRTC library with minimal resource usage and excellent performance
🔒 Complete Self-Hosting: Full data control without relying on third-party services
🛡️ Secure and Reliable: Built-in SRTP encryption transmission and complete certificate authentication system
🌐 Cross-Platform Compatibility: Supports mainstream operating systems to meet different environment needs
⚡ Advanced Technology: Supports H264/AV1 video encoding and Opus audio encoding
🎛️ Simple to Use: Quick connections via peer ID

Through this detailed guide, you should be able to:

Successfully Compile: Master CrossDesk compilation and execution methods
Deploy Server: Use Docker to quickly deploy self-hosted servers
Configure Certificates: Generate and configure necessary security certificates
Solve Problems: Handle common deployment and usage issues

CrossDesk is particularly suitable for the following scenarios:

Enterprise and individual users who need complete control over data security
Scenarios with high performance requirements for remote desktop
Self-hosting needs to avoid dependence on third-party services
Mixed environments requiring cross-platform remote access

It’s recommended to start with basic compilation and execution, then gradually configure self-hosted servers and certificate systems. If you encounter problems, you can refer to the Project Documentation or seek help in GitHub Issues.

Table of Contents