This article covers troubleshooting Splashtop remote connections to Linux devices only. For Windows troubleshooting, see Troubleshoot Splashtop Remote connection to Windows agents. For Mac, see Troubleshoot Splashtop Remote connection to Mac agents. For general prerequisites (firewall, ports, whitelisting), see Firewall settings for Atera's integrations.

Important: Linux remote access limitations

Before troubleshooting, be aware of the following Linux-specific limitations:

• Remote connections via Splashtop on Linux are not supported on headless devices (devices without a graphical interface). The device must have a monitor or a virtual display configured.
• You cannot start a remote session from a Linux device to any other device (Windows, Mac, or Linux). There is no Splashtop for RMM installer for Linux. Remote access via Splashtop is only supported when connecting from a Windows or Mac device to a Linux device.
• Wayland is not supported. The Linux device must be running an X11-based desktop environment. If the device uses Wayland (e.g., Ubuntu with KDE on Wayland), Atera may detect the system as headless and disable the Connect button. Switch to an X11 session to resolve this.
• Splashtop supports Raspberry Pi 2 or newer. For Raspberry Pi-specific setup, refer to the Splashtop Linux Streamer documentation.

Prerequisites

Ensure all of the following are met before troubleshooting:

Supported distributions

Remote access will not work on unsupported distributions. Your device must be running one of the following:

• Debian 11 (and above)
• Ubuntu 18 (and above)
• CentOS Stream
• Red Hat 8 (and above)

Network requirements

• Firewall settings for Atera's integrations — Verify that all required Splashtop servers are whitelisted. All Splashtop cloud traffic is outbound only — no inbound ports need to be opened.
• The following domains must be whitelisted:
  • *.splashtop.com (Global region)
  • *.splashtop.eu (EU region — required if your Atera account is on the EU stack)
• The following outbound ports must be open:
  • Port 443 (TCP) — Primary connection for all Splashtop traffic
  • Port 80 (TCP) — Required for Splashtop Streamer auto-updates via CloudFront
  • Port 6783 (TCP) — Used for local same-network connections
  • Port 3479 (UDP) — Used for QUIC-optimized end-to-end connections
• If your network uses DPI (Deep Packet Inspection) or SSL/TLS inspection, add *.splashtop.com and *.splashtop.eu to your SSL inspection bypass list. Splashtop currently supports RSA-based TLS certificates only.

Desktop environment requirements (especially for VMs)

Splashtop requires a graphical desktop environment to function. For Linux VMs or headless servers where you want to enable remote access, ensure the following are installed and configured:

• GNOME desktop environment (or another supported X11-based DE)
• LightDM as the display manager (required for Splashtop's virtual display)
• Xrdp for remote desktop connections
• Virtual display configured if no physical monitor is present
• PulseAudio for sound support, configured for system mode
• DBus running for inter-process communication

For detailed setup instructions for Linux VMs, see Splashtop for Linux.

Fix Splashtop remote access on Linux

If you have issues connecting to a Linux device via Splashtop, follow these steps:

1. Run the Splashtop connectivity check: Open www.splashtop.com/check on the affected device as a quick first diagnostic.

2. Verify the desktop environment is X11: Run the following command in Terminal:

echo $XDG_SESSION_TYPE

If the output is wayland, you must switch to an X11 session. Splashtop does not support Wayland. Log out, select an X11/Xorg session from the login screen, and log back in.

3. Verify the display manager: Splashtop requires LightDM. Check which display manager is active:

cat /etc/X11/default-display-manager

If it does not show /usr/sbin/lightdm, install and set LightDM:

sudo apt install lightdm
sudo dpkg-reconfigure lightdm

4. Verify the Splashtop Streamer service is running:

sudo systemctl status splashtop-streamer

If the service is not running or has errors, restart it:

sudo systemctl restart splashtop-streamer

If the service fails to start, the Streamer may not be installed correctly. See Splashtop for Linux for setup instructions.

5. Run the Splashtop connectivity and diagnostic script: Run the script below to test connectivity to all Splashtop servers, check port 80, and detect SSL inspection.

Fix Splashtop issues script Linux (.sh)

This script does the following:

1. Tests connectivity to all required Splashtop servers — both Global and EU regions.
2. Checks port 80 — verifies that auto-updates can be downloaded.
3. Detects SSL/TLS inspection — checks if the TLS certificate is legitimate and uses RSA.
4. Checks environment — verifies session type (X11 vs Wayland), display manager, and Splashtop Streamer service status.
5. Performs maintenance — clears cached Splashtop agent packages and restarts the Streamer service.

Upload this script to your Atera instance as a .sh file:

• Create, upload, and generate scripts
• Run a script

Important Note: Please ensure that you set the script as .sh.

log_file="/Library/Application Support/com.atera.ateraagent/Agent/packages/AgentPackageSystemTools/SPLogs.txt"; if [ ! -d "$(dirname "$log_file")" ]; then log_file="/tmp/splashtop_diag.txt"; fi; write_log() { echo "$1" | tee -a "$log_file"; }; write_log "=== SPLASHTOP LINUX DIAGNOSTIC ==="; write_log ""; write_log "=== ENVIRONMENT CHECKS ==="; session_type=$(echo $XDG_SESSION_TYPE 2/dev/null); if [ -z "$session_type" ]; then session_type=$(loginctl show-session $(loginctl | grep $(whoami) | awk '{print $1}') -p Type 2/dev/null | cut -d= -f2); fi; if [ -z "$session_type" ]; then write_log "Session Type: UNABLE TO DETERMINE (script may be running as root/system)"; elif echo "$session_type" | grep -qi "wayland"; then write_log "Session Type: $session_type - WARNING: Wayland is NOT supported by Splashtop. Switch to X11."; else write_log "Session Type: $session_type - OK"; fi; if [ -f /etc/X11/default-display-manager ]; then dm=$(cat /etc/X11/default-display-manager); write_log "Display Manager: $dm"; if echo "$dm" | grep -qi "lightdm"; then write_log "Display Manager Check: OK (LightDM detected)"; else write_log "Display Manager Check: WARNING - Splashtop requires LightDM. Current: $dm"; fi; else write_log "Display Manager: UNABLE TO DETERMINE"; fi; if systemctl is-active --quiet splashtop-streamer 2/dev/null; then write_log "Splashtop Streamer Service: RUNNING"; else write_log "Splashtop Streamer Service: NOT RUNNING or NOT INSTALLED"; fi; write_log ""; check_connection() { local domain=$1; local url="https://$domain/api/fulong/v3/echo/check-relay"; write_log "Checking connection to $domain..."; local response=$(curl -s -w "%{http_code}" -o /tmp/curl_output.txt --max-time 10 "$url"); local http_code="${response: -3}"; local content=$(cat /tmp/curl_output.txt 2/dev/null); if [ "$http_code" = "200" ] && echo "$content" | grep -q '"result".*20200'; then write_log "$domain : $http_code - SUCCESS"; elif [ "$http_code" = "200" ]; then write_log "$domain : $http_code - UNEXPECTED RESULT"; else write_log "$domain : ERROR - HTTP $http_code"; fi; }; write_log "=== GLOBAL REGION SERVERS ==="; for domain in st-v3.api.splashtop.com st-v3-g3.api.splashtop.com st-v3-src.api.splashtop.com st-v3-src-g3.api.splashtop.com st-relay-v3.api.splashtop.com st-relay-v3-g3.api.splashtop.com st-premium-v3.api.splashtop.com st-premium-v3-g3.api.splashtop.com; do check_connection "$domain"; done; write_log ""; write_log "=== EU REGION SERVERS ==="; for domain in st-v3.api.splashtop.eu st-v3-g3.api.splashtop.eu st-v3-src.api.splashtop.eu st-v3-src-g3.api.splashtop.eu st-relay-v3.api.splashtop.eu st-relay-v3-g3.api.splashtop.eu st-premium-v3.api.splashtop.eu st-premium-v3-g3.api.splashtop.eu; do check_connection "$domain"; done; write_log ""; write_log "=== PORT 80 CHECK (Auto-updates) ==="; port80_code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "http://www.splashtop.com" 2/dev/null); if [ "$port80_code" != "000" ]; then write_log "Port 80 (HTTP): REACHABLE (HTTP $port80_code)"; else write_log "Port 80 (HTTP): BLOCKED - Splashtop Streamer auto-updates may fail"; fi; write_log ""; write_log "=== SSL/TLS INSPECTION CHECK ==="; ssl_issuer=$(echo | openssl s_client -connect st-v3.api.splashtop.com:443 2/dev/null | openssl x509 -noout -issuer 2/dev/null); if [ -z "$ssl_issuer" ]; then write_log "SSL Certificate Issuer: UNABLE TO CHECK - Could not establish TLS connection"; elif echo "$ssl_issuer" | grep -qiE "amazon|splashtop|starfield|digicert"; then write_log "SSL Certificate Issuer: LEGITIMATE ($ssl_issuer)"; else write_log "SSL Certificate Issuer: WARNING - Unexpected issuer: $ssl_issuer - Possible SSL/DPI inspection detected"; fi; cert_algo=$(echo | openssl s_client -connect st-v3.api.splashtop.com:443 2/dev/null | openssl x509 -noout -text 2/dev/null | grep "Public Key Algorithm" | head -1 | awk -F: '{print $2}' | xargs); if echo "$cert_algo" | grep -qi "rsa"; then write_log "Certificate Algorithm: RSA - Compatible with Splashtop"; elif [ -n "$cert_algo" ]; then write_log "Certificate Algorithm: $cert_algo - WARNING: Splashtop requires RSA."; else write_log "Certificate Algorithm: UNABLE TO DETERMINE"; fi; write_log ""; write_log "=== MAINTENANCE ==="; folder_to_delete="/Library/Application Support/com.atera.ateraagent/Agent/packages/AgentPackageSTRemote"; alt_folder="/opt/atera/packages/AgentPackageSTRemote"; if [ -d "$folder_to_delete" ]; then rm -rf "$folder_to_delete" && write_log "Deleted package: $folder_to_delete" || write_log "Failed to delete: $folder_to_delete"; elif [ -d "$alt_folder" ]; then rm -rf "$alt_folder" && write_log "Deleted package: $alt_folder" || write_log "Failed to delete: $alt_folder"; else write_log "No cached Splashtop package found to clean"; fi; if systemctl is-active --quiet splashtop-streamer 2/dev/null; then systemctl restart splashtop-streamer 2/dev/null && write_log "Restarted splashtop-streamer service" || write_log "Failed to restart splashtop-streamer service"; else write_log "splashtop-streamer service not found - skipping restart"; fi; write_log ""; write_log "=== SCRIPT COMPLETED ==="

Understanding the script output

The script output is organized into sections. Review each section to identify the root cause.

Environment checks

Session Type — Must show x11. If it shows wayland, switch to an X11 session. If it says "UNABLE TO DETERMINE," the script is running as system/root and cannot detect the session — verify manually by running echo $XDG_SESSION_TYPE in a local terminal.

Display Manager — Must show lightdm. If it shows GDM or another display manager, install and configure LightDM (see prerequisites above).

Splashtop Streamer Service — Must show RUNNING. If NOT RUNNING, the Streamer may not be installed. See Splashtop for Linux for installation instructions.

Server connectivity (Global and EU regions)

Same output format as the Mac and Windows scripts:

• ✅ domain : 200 - SUCCESS — Server reachable. No action needed.
• ⚠️ domain : 200 - UNEXPECTED RESULT — Likely SSL/DPI inspection. Add *.splashtop.com and *.splashtop.eu to your SSL inspection bypass list.
• ❌ domain : ERROR - HTTP [code] — Server unreachable. Whitelist the domain, ensure outbound ports 443 and 80 are open, check DNS resolution.

If your account is on the Global stack, Global servers must pass. If on the EU stack, EU servers must pass.

Port 80, SSL/TLS inspection, and maintenance

These sections work identically to the Mac and Windows versions. See the Mac troubleshooting article for detailed guidance on interpreting port 80, SSL certificate issuer, and certificate algorithm results.

After running the script

If all checks pass (environment OK, servers reachable, no SSL inspection), wait 2 minutes and try connecting again from the Atera console.

If the script identified issues, address them in this priority:

1. Wayland detected? → Switch to an X11 session. This is the most common cause of "Connect button greyed out."
2. Wrong display manager? → Install and configure LightDM.
3. Streamer not running? → Verify Splashtop Streamer is installed. Follow the setup instructions in Splashtop for Linux.
4. SSL inspection detected? → Add Splashtop domains to your bypass list.
5. Server connectivity errors? → Whitelist domains and open outbound ports.

"Connect" button is greyed out

If the Connect button is greyed out for a Linux device in the Atera console, the device is being detected as headless (no graphical interface). This happens when:

• The device is using Wayland instead of X11. Verify with echo $XDG_SESSION_TYPE and switch to X11 if needed.
• No physical monitor or virtual display is connected. For VMs, configure a virtual display as described in the Splashtop for Linux setup instructions.
• The desktop environment is not installed or not running. Install GNOME or another X11-compatible DE.

Splashtop won't connect — cleanup and reinstall

If the Splashtop Streamer is installed, the service is running, the environment checks pass, and servers are reachable — but the connection still fails — perform a cleanup:

Step 1: Stop and remove the Splashtop Streamer

sudo systemctl stop splashtop-streamer 2/dev/null; sudo pkill -9 -f "Splashtop" 2/dev/null; sudo pkill -9 -f "SRStreamerDaemon" 2/dev/null

Step 2: Clear cached Splashtop agent packages

sudo rm -rf /Library/Application\ Support/com.atera.ateraagent/Agent/packages/AgentPackageSTRemote 2/dev/null; sudo rm -rf /opt/atera/packages/AgentPackageSTRemote 2/dev/null

Step 3: Reinstall the Splashtop Streamer

You can reinstall by either:

• Initiating a remote session from the Atera console — this triggers automatic Streamer deployment.
• Or manually installing the Streamer. See Splashtop Streamer and Splashtop for RMM Installation.

Step 4: Verify the Streamer is running

sudo systemctl status splashtop-streamer

Note: If the cleanup and reinstall still do not resolve the issue, please contact our support team. The issue may require investigation from our engineering team.