On-Premises

How it works

HopToDesk uses two kinds of servers. The signal server helps devices find each other and set up a session. The TURN relay carries session traffic only when a direct connection between the two devices is not possible.

Sessions are encrypted end to end, so neither server can read your screen, files or chat. The signal server only sees device IDs and connection requests.

The installer on this page sets up the signal server. Relay traffic goes through the HopToDesk relay by default, or through your own TURN server if you provide one.

The dashboard stays a hosted service. Devices on a self-hosted network can still be linked to it for management, and the dashboard can push the network settings to them.

Before you start

• A server running Ubuntu 18.04 to 24.04, or a Windows server.
• Root or sudo access on that server.
• An IP address or hostname that all your devices can reach. For a network that never leaves your LAN, a private address is enough.
• TCP port 80 open on the server firewall for your devices.
• If you want your own relay, the host, port, username and password of your TURN server.

Step 1: Install the signal server on Linux

1. Log in to the server as root, or as a user with sudo rights.
2. At the top of this page, choose LAN + Default Relay or Custom TURN Server. The install command changes with your choice.
3. Click Copy, paste the command into the terminal and press Enter.
4. Wait until the script finishes. A fresh server can take a few minutes to install its packages.
5. At the end the script prints HopSignal Setup Complete, followed by your server address and a ready-made network settings block. Keep that output, you need it in step 3.

cd /home && curl -o hsinstall.sh -sL https://www.hoptodesk.com/hs/hsinstall && sh hsinstall.sh

With your own TURN server, add its four values to the end of the command in this order: host, port, username, password.

sh hsinstall.sh turn.example.com 443 myuser mypassword

What the script does

• Installs the build tools and OpenSSL libraries it needs with apt.
• Downloads the signal server binary into the folder /home/hopsignal.
• Creates a systemd service named hopsignal and starts it at every boot.
• Adds a cron watchdog that restarts the service if it stops answering, and rotates the log when it grows past 100 MB.
• Opens TCP port 80 in ufw when ufw is active.

Step 1 on Windows: Run the signal server

1. Switch the OS toggle at the top of this page to Windows and click Download. You get one file named hopsignal.exe.
2. Create a folder such as C:\hopsignal and move hopsignal.exe into it.
3. In the same folder, create an empty text file named fedlist.txt.
4. The Windows build also expects a TLS certificate and its private key in PEM format. Any pair works, including a self-signed one. Save them as cert.pem and key.pem in the same folder.
5. Open a Command Prompt as administrator and start the server.

cd C:\hopsignal
hopsignal.exe --ADDR 0.0.0.0:80 --WSS_ADDR 0.0.0.0:443 --CERT cert.pem --KEY key.pem --FEDLIST fedlist.txt --FEDADDR 127.0.0.1:82 --FEDPWD 123456789 --LOGFILE hs.log

If you have OpenSSL, this command creates a self-signed certificate pair:

openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 3650 -subj "/CN=hopsignal"

Allow the port through Windows Firewall:

netsh advfirewall firewall add rule name="HopSignal" dir=in action=allow protocol=TCP localport=80

To keep the server running after a reboot, register it as a scheduled task that starts at boot under the SYSTEM account:

schtasks /Create /TN HopSignal /SC ONSTART /RU SYSTEM /TR "C:\hopsignal\hopsignal.exe --ADDR 0.0.0.0:80 --WSS_ADDR 0.0.0.0:443 --CERT C:\hopsignal\cert.pem --KEY C:\hopsignal\key.pem --FEDLIST C:\hopsignal\fedlist.txt --FEDADDR 127.0.0.1:82 --FEDPWD 123456789 --LOGFILE C:\hopsignal\hs.log"
schtasks /Run /TN HopSignal

Step 2: Check that the server is running

On Linux, check the service and the log:

sudo systemctl status hopsignal
tail /home/hopsignal/hs.log

On Windows, confirm that the port is listening:

netstat -an | find ":80 "

From any computer, test the WebSocket port. Replace SERVER_IP with your server address. A healthy server answers with HTTP/1.1 101 Switching Protocols.

curl -i -N -m 5 -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" http://SERVER_IP:80/

Step 3: Point your devices at the server

Every device reads its network settings from a small JSON document. This is the block the installer printed at the end of step 1. Replace SERVER_IP with your server address, and fill in the TURN block if you run your own relay.

{
  "turnservers": [
    {
      "protocol": "turn",
      "host": "turn.hoptodesk.com",
      "port": "443",
      "username": "hoptodesk",
      "password": "hoptodesk1234"
    }
  ],
  "rendezvous": {
    "host": "SERVER_IP",
    "port": "80"
  },
  "winversion": "1.0.0",
  "macversion": "1.0.0",
  "linuxversion": "1.0.0",
  "none": "none"
}

The rendezvous block is your signal server. Use the key rendezvousssl instead of rendezvous when the server is reached over TLS, for example a Cloudflare Worker or an AWS deployment. The turnservers list holds one or more relays. Set the protocol to turn for a plain connection or to turn-tls for a TLS connection. Leave the version keys as they are.

There are three ways to give this document to your devices. Pick the one that fits your setup.

Option A: Put an api.json file on each device

Save the document as a file named api.json in the HopToDesk configuration folder, then restart HopToDesk. The app reads the file at startup and no longer contacts the HopToDesk API.

On Linux the background service runs as root and reads the file under /root, while the app you open reads the file in your own home folder. Put a copy in both places.

Option B: Host the file at a URL and select it in the app

1. Upload api.json to any web server your devices can reach. HTTPS is recommended.
2. In HopToDesk, click the gear icon to open Settings.
3. Under Network, click Choose Network.
4. Select Custom Network Settings, paste the URL of your file and confirm.
5. HopToDesk downloads the file, checks that it contains a valid rendezvous entry and a turnservers list, and then reconnects through your server.

To return to the public network, open Choose Network again and select HopToDesk Network.

Option C: Push the settings from the dashboard

If your devices are linked to the HopToDesk dashboard, you can set the network once for the whole account. A custom client built from the dashboard ships with these settings built in.

1. Sign in to the dashboard as an owner or admin and open Settings.
2. Under Network Settings, select Custom Network.
3. Enter the signal server host, its port and WS as the protocol. Add a TURN server if you run your own relay, or leave it empty to keep the HopToDesk relay.
4. Click Save Network Settings. Every linked device receives the new settings and applies them without a reinstall.

Run your own TURN relay (optional)

Sessions that cannot connect directly are relayed through the HopToDesk relay by default. To keep all traffic on your own infrastructure, run a TURN server. Any standard TURN server works, and coturn is a common choice on Linux.

1. Install coturn on the relay server.

sudo apt install coturn

2. Edit /etc/turnserver.conf and set at least the values below. Replace the realm, the credentials and the public IP with your own.

listening-port=443
fingerprint
lt-cred-mech
user=myuser:mypassword
realm=example.com
external-ip=PUBLIC_IP

3. If /etc/default/coturn contains a TURNSERVER_ENABLED line, uncomment it. Then enable and start the service.

sudo systemctl enable --now coturn
sudo systemctl restart coturn

4. Open the listening port for TCP and UDP, plus the UDP relay range 49152 to 65535, on the relay firewall.
5. Give the relay to your devices: run the installer again with the four TURN values, or edit the turnservers block in your network settings. Use turn-tls as the protocol if your relay terminates TLS.

Manage the server on Linux

sudo systemctl status hopsignal
sudo systemctl restart hopsignal
sudo systemctl stop hopsignal
tail -f /home/hopsignal/hs.log

To update the server, stop the service and run the install command again. It downloads the current binary and rewrites the service.

To remove the server together with its service and cron entries:

cd /home && curl -o hsinstall.sh -sL https://www.hoptodesk.com/hs/hsinstall && sh hsinstall.sh remove

Troubleshooting

• The ID stays on Generating, or the app keeps connecting to the network: the device cannot reach the signal server. Check that the service is running, that port 80 is open, and that the address in your network settings is correct.
• Devices connect on the LAN but not from outside: the relay is not reachable. With the default relay, devices need outbound access to turn.hoptodesk.com on port 443. With your own relay, check its firewall rules and credentials.
• The app ignores api.json: make sure the file is valid JSON without trailing commas, that it sits in the right folder, and that you restarted HopToDesk. The app log contains the line Loaded local api.json when the file was picked up.
• Port 82 is the federation port for linking several of your own signal servers. Keep it closed to the internet.
• The signal server stores no session data. If something looks stuck, restart the service. Devices reconnect on their own within about a minute.