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 64-bit Linux server with systemd, such as Ubuntu or Debian, 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. It takes less than a minute.
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.

curl -o hsinstall.sh -sL https://www.hoptodesk.com/hs/hsinstall && sudo 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.

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

What the script does

• Downloads the signal server for your processor, Intel, AMD or ARM, into the folder /home/hopsignal.
• Checks the download against the published SHA256SUMS list and stops without changes when it does not match.
• Creates a systemd service named hopsignal and starts it at every boot.
• Starts the server with the recommended connection limits and a random federation password, stored in /home/hopsignal/hopsignal.env with root-only access.
• 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. Open a Command Prompt as administrator and start the server.

cd C:\hopsignal
for /f %i in ('powershell -NoProfile -Command "[guid]::NewGuid().ToString('N')"') do @(setx /M FEDPWD %i >nul & set FEDPWD=%i)
hopsignal.exe --ADDR 0.0.0.0:80 --FEDLIST fedlist.txt --FEDADDR 127.0.0.1:82 --LOGFILE hs.log

The second line saves a random federation password as a Windows system setting, so it never appears on the server's command line.

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 --FEDLIST C:\hopsignal\fedlist.txt --FEDADDR 127.0.0.1:82 --LOGFILE C:\hopsignal\hs.log"
schtasks /Run /TN HopSignal

Step 1 with Docker: Run the signal server in a container

The image hoptodesk/hopsignal runs the same signal server on Intel, AMD and ARM hosts. Start it with the recommended limits:

docker run -d --name hopsignal --restart unless-stopped -p 80:80 \
  -e HS_MAX_MESSAGE_KB=64 -e HS_QUEUE_LIMIT=256 -e HS_MAX_CONNS=20000 \
  -e HS_CONNS_PER_IP=100 -e HS_LOOKUPS_PER_IP=20 \
  -e HS_IDLE_TIMEOUT=300 -e HS_UPGRADE_TIMEOUT=10 \
  hoptodesk/hopsignal

Each HS_ value turns on one limit: message size in KB, queued messages per connection, open connections, new connections and lookups per address each second, idle seconds and handshake seconds. Leave a value out and that limit stays off.

To link the container to your dashboard account automatically, use the Docker command from Set up a private network in the dashboard. It adds HS_SETUP_TOKEN and HS_DASHBOARD_URL, and the server reports its address once, at its first start.

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 "

With Docker, check the container and its log:

docker ps --filter name=hopsignal
docker logs hopsignal

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. 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.

Write each port number in quotes, as in the example above. The app ignores a port written as a plain number.

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, put a second copy in /root/.config/hoptodesk. The app uses that copy at the login screen, before a user signs in.

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 (Default).

On Android and iOS, open Settings, turn off Use HopToDesk Network in the Network section, then enter the URL of your file. Phones managed through an EMM can receive the same URL with the managed setting custom_api_url.

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.

New server: in the dashboard, open Settings, Network Settings, Set up a private network. Pick In my AWS account or On my own server. The server reports its address when it starts, and every linked device gets the settings. Nothing to type.

A server you already run: enter its settings by hand.

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:

curl -o hsinstall.sh -sL https://www.hoptodesk.com/hs/hsinstall && sudo 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.