HopToDesk Help Center

Download & Installation

HopToDesk runs on every major desktop and mobile platform. Download the latest version for your system from www.hoptodesk.com.

Windows

• 32-bit .exe, 64-bit .exe, or ARM64 .exe - download and run. HopToDesk launches immediately in portable mode. Click Install (bottom-left of the main window) to install the background service so the device accepts incoming connections even when the app isn't open. See Portable vs Installed Mode.
• MSIX and Microsoft Store - sandboxed installations, ideal for managed Windows devices.
• Chocolatey - install with choco install hoptodesk.
• Windows XP - a separate XP-compatible build is available for legacy systems.

macOS

• .dmg for Intel or .dmg for Apple Silicon - download the matching variant, open the DMG, and drag HopToDesk.app to your Applications folder.
• On first launch, macOS prompts you to grant permissions for Screen Recording, Accessibility, and Input Monitoring (see macOS Permissions).
• HopToDesk runs as an installed application on macOS - there is no separate "portable" variant.

Linux

• Debian / Ubuntu: .deb package - sudo dpkg -i hoptodesk.deb.
• Fedora / openSUSE: .rpm package.
• Manjaro / Arch: .zst package.
• Distribution-agnostic: AppImage or Flatpak.
• Installers register a systemd service for background operation.

Raspberry Pi

• 32-bit (armhf) .deb and 64-bit (arm64) .deb packages are available. Install with sudo dpkg -i.

FreeBSD

• amd64 .pkg - install with pkg install hoptodesk-freebsd-amd64.pkg.
• FreeBSD 13+ is required; both amd64 and aarch64 are supported.
• The FreeBSD build uses a WebKitGTK-based UI but is wire-compatible with the standard Windows/macOS/Linux client.

ChromeOS

• Install from the Google Play Store on ChromeOS devices that support Android apps.

Android

• Install from the Google Play Store or download the .apk directly from the website.
• The website .apk includes full host mode (accept incoming connections). The Play Store version is client-only.

iOS

• Available on the App Store. iOS supports outgoing connections only (client mode).

Portable vs Installed Mode (Windows)

Portable vs installed is a Windows-only distinction. On macOS, Linux, and FreeBSD the download package installs HopToDesk as a regular application and it always runs as a normal installed app (with a LaunchAgent/LaunchDaemon on macOS or a systemd service on Linux).

Portable Mode (Windows)

• Just download the .exe and run it - no installation required.
• Great for one-time support sessions or running from a USB stick.
• Supports unattended access as long as you set a permanent password and leave the application running.
• No Windows service is installed, so HopToDesk only accepts incoming connections while the app window is open. Closing the app stops connectivity until you relaunch it.

Installed Mode (Windows)

• Click the Install button in the bottom-left corner of the main window (or run the installer with --silent-install).
• Installs a background service that starts with Windows and accepts incoming connections even when no one is logged in.
• Your Device ID remains the same across reboots.
• Required for features that need elevated privileges, such as showing the Windows login screen, UAC prompts, and privacy mode.

Minimum System Requirements

Your First Connection

Connecting to a remote computer with HopToDesk takes just a few steps:

1. On both computers: Open HopToDesk. Each device will display a unique Device ID and a Password.
2. On your computer: Enter the remote computer's Device ID in the "Enter Remote ID" field.
3. Click Connect (or press Enter).
4. Enter the remote computer's password when prompted.
5. You're now connected and can see and control the remote desktop.

Connection Types

HopToDesk supports several connection modes. Select the type from the dropdown next to the Connect button:

Unattended Access

Unattended access lets you connect to a remote computer without anyone present to accept the connection. For best security it is off by default, and you turn it on with the dedicated toggle right next to the password field on the main window.

Setup (one click)

1. Find the Unattended Access toggle on the right side of the password row in the main window.
2. Flip it on. The toggle sets a permanent password on the device so it can be reached at any time, even when no one is present.
3. To view, change, or manage the password itself, click the small Set pill (pen icon) on the password row.
4. Note the Device ID - you'll need it plus the permanent password to connect.

Now you can connect at any time using the Device ID and permanent password. Flip the toggle off whenever you want to return to temporary-password-only mode.

Portable vs Installed

• Portable Windows / unattended macOS, Linux, FreeBSD: unattended access works as long as HopToDesk is running on the remote machine.
• Installed Windows: also accepts connections across reboots and before a user logs in, because the HopToDesk service runs in the background. Recommended when you need always-on remote access. See Portable vs Installed Mode.

Direct IP Access

HopToDesk supports direct IP connections, which bypass the signal server entirely - useful for LAN-only setups or environments with strict outbound restrictions.

• Simply enter the IP address of the remote computer (and optionally :port) in place of a Device ID to connect directly.
• The default port is 21118 TCP. You can change it by clicking the pen icon next to Enable Direct IP Access in the menu near the ID.
• The remote device must have Enable Direct IP Access turned on in its permissions.

Quick Support

Quick Support launches a simplified version of HopToDesk that accepts only incoming connections - ideal for end users receiving one-time support.

• Launch HopToDesk with the --qs parameter, or rename the executable so the filename ends in -qs (e.g. hoptodesk-qs.exe).
• A minimal window appears showing only the ID/password and incoming-connection settings.
• Outgoing connection UI is hidden, so the recipient can't accidentally connect somewhere else.

Remote Terminal

Remote Terminal opens an interactive shell session on the remote device without sharing its screen. The remote system runs a pseudo-terminal (PTY) and streams ANSI-colored output back to your window, so you get the full shell experience (prompts, colors, editors like vim or nano) with a fraction of the bandwidth of a full remote desktop session.

Starting a Terminal Session

Pick either method:

• From the Address Book: right-click a saved device and choose Remote Terminal.
• From the command line: launch HopToDesk with --terminal followed by the Device ID.

You'll be prompted for the device's password (and 2FA code, if enabled) just like a normal connection. Once connected, the terminal window shows the remote shell with a status bar and a Disconnect button.

Keyboard Shortcuts

Features & Notes

• ANSI colors: 16-color SGR sequences (foreground, background, bold, bright) are rendered as styled output.
• Auto-resize: the terminal sends resize events when you change the window size so the remote shell reflows correctly.
• Multiple terminals: open several Remote Terminal windows to the same device for parallel sessions.
• Low overhead: text-only protocol, so it works smoothly over slow or high-latency links.
• Permissions: the remote user must allow the connection on first use, just like any other session type. On Windows-installed mode the terminal inherits the service account's shell.

Address Book & Tags

Save frequently accessed devices to your address book for quick access:

• Add a device: After connecting, save the device to your address book, or add it manually by entering the Device ID.
• Tags: Organize devices with custom tags (e.g., "Office", "Servers", "Home"). A device can have multiple tags.
• Filter: Click a tag in the sidebar to filter your address book by that category.
• Quick connect: Double-click any saved device to connect instantly.

LAN Discovery

HopToDesk can automatically discover other HopToDesk devices on your local network.

• Go to the Address Book tab and look for the LAN section.
• Devices running HopToDesk on the same network will appear automatically.
• LAN connections are direct - no relay server is used, which means faster performance.

LAN discovery can be enabled or disabled in Settings > Network.

Toolbar Overview

During a remote session, a toolbar appears at the top of the screen with quick access to all session features:

Display & Quality Settings

Customize how the remote desktop appears on your screen. Access these from the Display Settings button in the toolbar.

View Modes

• Original: Shows the remote desktop at its native resolution. You may need to scroll if the remote screen is larger than your window.
• Shrink: Scales the remote desktop down to fit your window. Best for viewing large remote screens on smaller monitors.
• Stretch: Stretches the remote desktop to fill your window completely.

Image Quality

• Good: High image quality with more bandwidth usage.
• Balanced: A compromise between quality and performance.
• Optimize Reaction Time: Lowest quality but fastest response - ideal for slow connections.
• Custom: Manually set bitrate and frame rate.

Codec Selection

Choose the video codec used for the remote desktop stream:

• VP8 / VP9: Software codecs that work on all systems.
• AV1: Modern codec with excellent compression (requires compatible hardware).
• H.264 / H.265: Hardware-accelerated codecs for better performance when supported.

Additional Options

• True Color (4:4:4): Full color accuracy - useful for design work or reading fine text.
• Show Remote Cursor: Display the remote user's cursor on your screen.
• Mute Audio: Silence audio streaming from the remote machine.
• Disable Clipboard: Prevent clipboard sharing between local and remote.
• Lock After Session: Automatically lock the remote computer when you disconnect.

Multiple Screens & Displays

When the remote device has more than one monitor, each remote display is represented by a screen icon in the top-left area of the connection toolbar.

• Click a screen icon to switch the view to the corresponding monitor of the remote device.
• To view multiple monitors simultaneously, open HopToDesk in several windows and connect to the same device in each one - then select a different display in each window to watch multiple screens at once.

File Transfer

Transfer files between your local computer and the remote machine during a session. Uploads and downloads support resume if the transfer is interrupted.

How to Use

1. Click the File Transfer icon in the toolbar, or start a connection in File Transfer mode.
2. The file transfer panel shows your local files on the left and remote files on the right.
3. Navigate to the desired folders on each side.
4. Select files or folders and click the arrow buttons to transfer, or drag and drop files between the panels.

Features

• Multi-select files for batch transfers.
• Create new folders on either side.
• Delete and rename files remotely.
• Show or hide hidden files.
• Transfer progress tracking with the ability to cancel.

Remote Printing

Remote printing allows you to print documents from a remote computer to a printer connected to your local machine. This feature is available on Windows and macOS.

Setup (on the Remote Computer)

1. Open HopToDesk on the remote computer (the one you connect to).
2. Go to Settings.
3. Find and enable "Enable Remote Printing".

Once enabled, a virtual printer called "HopToDesk Printer" is set up on the remote machine.

Printing During a Session

1. Connect to the remote computer from your local machine.
2. You will see a printer icon in the session toolbar (it only appears when the remote computer has remote printing enabled).
3. Click the printer icon to select a local printer from the list of printers available on your computer.
4. Optionally, check "Always use this printer" so you won't be prompted each time.
5. Now, when you print a document on the remote computer (from any application), select "HopToDesk Printer" as the printer. The print job will be sent to your selected local printer.

Chat

Communicate with the remote user during a session without needing a separate messaging tool.

• Click the Chat icon in the toolbar to open the chat window.
• Type messages and press Enter to send.
• Both the local and remote user can see and respond to messages.
• Chat history is available for the duration of the session.

Audio Streaming

HopToDesk can stream audio from the remote computer to your local machine.

• Audio streaming is enabled by default during remote desktop sessions.
• To mute, go to Display Settings in the toolbar and enable "Mute".
• The remote computer can select which audio input device to share in Settings > Audio Input.

Session Recording

Record your remote sessions for training, auditing, or review purposes. Recordings are saved locally in .webM video format.

• Toggle the recording icon near the top right of the main connection window to start or stop recording.

Where Recordings Are Saved

Keyboard & Mouse Control

HopToDesk provides several keyboard layout modes and special key combinations for controlling the remote computer.

Keyboard Modes

Special Actions

Available from the Actions menu in the toolbar:

• Ctrl + Alt + Delete: Send the Ctrl+Alt+Del sequence to the remote computer.
• Lock Screen: Lock the remote computer's screen.
• Block User Input: Temporarily block keyboard and mouse input on the remote computer (Windows only). Useful when performing maintenance.
• Request Elevation: Request administrator privileges on the remote machine (for UAC prompts on Windows).
• Restart: Restart the remote computer.

Modifier Key Swap

When connecting between macOS and Windows, you can swap Ctrl and Command keys in Display Settings for a more natural typing experience.

Privacy Mode

Privacy mode blacks out the remote computer's screen so that anyone physically present cannot see what you're doing. This is useful for sensitive tasks like entering passwords or accessing confidential data.

• Click the eye icon in the toolbar to toggle privacy mode.
• The remote screen will appear black to anyone looking at the physical monitor.
• You can still see and control the remote desktop normally.

Privacy mode is supported on Windows and macOS. It may require specific display driver support on Windows.

Screenshots

Capture a screenshot of the remote desktop during a session:

• Click the Screenshot icon in the toolbar (or use Ctrl+Shift+S).
• The screenshot is automatically saved to your clipboard and can be pasted into any application.

Switch Sides

Reverse the control direction so the remote user can control your computer instead.

• Click the Switch Sides icon in the toolbar.
• The remote user now sees and controls your desktop, while you see theirs.
• Useful for collaborative troubleshooting when the remote person needs to show you something on your own machine.

Port Forwarding / TCP Tunneling

Create secure TCP tunnels through HopToDesk to access services on the remote network.

Setup

1. Select Port Forwarding as the connection type before connecting.
2. Add a forwarding rule specifying the local port, remote port, and optionally the remote host.
3. Connect to the remote device.
4. Access the remote service by connecting to localhost:<local-port> on your machine.

Common Use Cases

• RDP tunneling: Forward port 3389 to access Remote Desktop through HopToDesk's encrypted tunnel.
• Database access: Tunnel to a remote database server that isn't exposed to the internet.
• Web services: Access internal web applications running on the remote network.

Passwords

HopToDesk uses two types of passwords to control access:

Temporary Password

• Generated automatically each time HopToDesk starts (in portable mode) or can be refreshed manually.
• Displayed in the main window next to your Device ID.
• Ideal for one-time support sessions - share it with the person helping you, then it changes next time.

Permanent Password

• Set manually in Settings.
• Does not change between sessions or restarts.
• Required for unattended access.

Two-Factor Authentication (2FA)

Add an extra layer of security by requiring a time-based code in addition to your password.

Setup

1. Click the three dots to the right of the ID under Your Desktop on the main window.
2. Select Enable Two-Factor Authentication.
3. Open an authenticator app (Google Authenticator, Authy, Microsoft Authenticator, etc.) and scan the QR code.
4. Enter the 6-digit verification code from your authenticator app to confirm.

Using 2FA

When someone connects to your computer, they will need to enter both:

1. Your password (temporary or permanent)
2. A 6-digit code from your authenticator app

Codes refresh every 30 seconds and have a small window of tolerance for clock differences.

Encryption

All HopToDesk connections are encrypted end-to-end. Your session data (screen content, keyboard input, file transfers, audio) is encrypted in transit and cannot be read by third parties, including HopToDesk servers.

• Connections use strong encryption protocols.
• A security code is displayed during connection that both parties can verify to confirm the connection is not intercepted.
• Direct (peer-to-peer) connections are used when possible. When a relay is needed, the data remains encrypted end-to-end.

Permissions

Control what remote users can do when connected to your computer. Configure these from the permissions menu on the main window:

During an active session, the connection manager on the remote computer shows all active permissions and allows toggling them individually.

Settings Overview

Open the Settings panel with the gear icon at the top of the main HopToDesk window. The panel is organized into six groups that appear in the order below. Each group is documented as its own topic for quick reference.

• Remote Access - what connected partners are allowed to do.
• Audio Input - microphone/system-audio streaming.
• Network - API, proxy, direct IP, LAN discovery.
• Security - incoming-connection master switch and 2FA.
• Appearance - dark theme and language.
• Dashboard - link to a HopToDesk Dashboard account.

Settings - Remote Access

The Remote Access group lists the permissions your device grants to incoming connections. Each row is a toggle.

For more detail on each permission, see the Permissions topic.

Settings - Audio Input

The Audio Input group appears when the device has a microphone or (on Windows) the "System Sound" loopback is available. It controls whether remote partners can listen to this device's audio.

Settings - Network

The Network group controls how HopToDesk reaches the signal servers, relays, and peers.

Settings - Proxy Settings

Tapping Proxy Settings in the Network group opens a dialog with the following fields:

Settings - Security

The Security group in the Settings panel exposes two switches. For full background on each, see the Security category in the sidebar.

Settings - Appearance

Settings - Dashboard

The Dashboard group shows your HopToDesk Dashboard link status.

• Enter Invite Code - tap to link this device to a HopToDesk Dashboard account using an invite code.
• Linked - once linked, the row shows the first few characters of the dashboard user ID. Tap the row again to unlink.

See Dashboard Integration for the benefits of linking, and dashboard.hoptodesk.com for how to obtain an invite code.

Choose Network

When HopToDesk launches, it loads the default API to fetch network and other settings. You can override this and point HopToDesk at a different API URL for greater control over the networking used by the app.

• Open the Choose Network option from the HopToDesk menu.
• Enter a custom API URL - HopToDesk will fetch its signal server, relay, and TURN settings from there.

API Override & Partial Self-Hosting / On-Premise

HopToDesk depends on an API to load the settings needed to make and receive connections. You can bypass the default API and load settings locally by creating an api.json file in the HopToDesk config directory:

Download the template api.json, copy it into the config folder above, and edit the values as needed. Keep the rendezvous JSON key unchanged (it points to the signal server) to continue using the HopToDesk signal server. Define your own TURN servers by editing the turnservers section.

When HopToDesk opens, it will use your custom api.json instead of fetching settings from the HopToDesk API - which also gives a small improvement in startup time.

MCP (Model Context Protocol) Server

HopToDesk includes a built-in MCP server so AI agents and automation tools can control and monitor HopToDesk programmatically. MCP uses JSON-RPC 2.0 and conforms to MCP protocol version 2024-11-05.

Transport Modes

Authentication

For WebSocket and TCP modes, the first message on each connection must be an auth token:

{"auth": "TOKEN"}

The token is generated automatically and written to a discovery file called mcp.json in the HopToDesk config directory:

{
  "mcp_version": "2024-11-05",
  "server": "hoptodesk-mcp",
  "version": "1.x.x",
  "transport": "websocket",
  "url": "ws://127.0.0.1:9333",
  "port": 9333,
  "token": "random-32-character-token",
  "pid": 12345
}

On macOS and Linux the discovery file is restricted to owner-only permissions (0600), and it is deleted automatically when HopToDesk exits. Stdio mode does not require authentication.

Configuring an AI Agent

For Claude Desktop (and other MCP-compatible agents), add HopToDesk as an MCP server in the agent config. Stdio mode is simplest - no token required:

{
  "mcpServers": {
    "hoptodesk": {
      "command": "/path/to/hoptodesk",
      "args": ["--mcp"]
    }
  }
}

For WebSocket mode, your agent reads mcp.json from the HopToDesk config directory to obtain the URL and token.

Available Tools

The MCP server exposes 27 tools organized into the following categories:

Screen & Input

• screenshot - Capture the display as a PNG. Supports cropping via x, y, width, height.
• get_window_list - List all visible windows with titles, positions, and sizes.
• mouse_click - Move the mouse to coordinates and click (left/right/middle, single or double).
• mouse_move - Move the mouse without clicking.
• type_text - Type text via keyboard input (unicode supported).
• key_press - Press a key or key combo (e.g. Return, ctrl+a, alt+F4).

Device Information

• get_device_info - Get this device's HopToDesk ID, version, platform, hostname, and signal server status.
• list_peers - List known peers with filters: all, recent, favorites, or lan.

Connection Management

• connect_to_peer - Initiate a remote connection. Types: connect, file-transfer, port-forward. Optional password.
• disconnect_peer - Close an active remote connection.
• list_active_connections - List all outgoing remote connections with type and status.
• list_incoming_connections - List peers connected to this device with authorization status and permissions.

Connection Control

• get_ui_state - Rich UI state: toolbar buttons, connection quality (speed/FPS/delay/codec), display info, permissions, dialogs, video dimensions, view settings.
• wait_for_event - Block until an event occurs (up to 60s). Events: connection_ready, connection_closed, dialog_appeared, dialog_dismissed, quality_stable.
• dismiss_dialog - Dismiss the current modal. Use a peer ID or "all".
• click_toolbar_button - Click a toolbar button or submenu. Buttons: fullscreen, chat, transfer-file, remote-print, recording, privacy-mode. Submenus use menu:item (e.g. action:ctrl-alt-del, display:original, keyboard:map).
• send_chat_message - Send a chat message to a connected remote peer.

Permissions

• switch_permission - Toggle incoming-connection permissions: keyboard, clipboard, audio, file, restart, recording.

Clipboard & Files

• get_clipboard / set_clipboard - Read or write the local clipboard.
• list_local_files - List directory contents on this device. Optionally include hidden files.
• read_local_file - Read a local file (text or base64 for binary, max 1 MB).

Remote Printing

• set_remote_printer - Configure the printer for remote print jobs. Use auto to pick the only available printer; omit the name to list available printers.
• test_print - Send a test print job to verify the remote print pipeline.

System Operations (Dashboard-enrolled devices only)

• exec_operation - Run a predefined system operation: get_system_info, disk_usage, list_processes, network_info, get_service_logs, ping_test, installed_software, restart_hoptodesk, kill_process, flush_dns, reboot_device, clear_temp_files, run_update_check.
• run_command - Execute an arbitrary shell command (cmd.exe on Windows, /bin/sh on macOS/Linux). Default timeout 30s, max 120s. Output truncated to 64 KB.

Security

• All transports bind to localhost only (127.0.0.1). MCP is never exposed to other machines.
• WebSocket and TCP modes require token authentication before accepting any commands.
• The mcp.json discovery file has restricted permissions on Unix systems.
• Destructive operations (run_command, exec_operation, disconnect_peer) are annotated as requiring confirmation, giving AI agents an opportunity to prompt the user before executing.

Command Line Options

HopToDesk supports a number of command line arguments on the desktop version:

Examples

hoptodesk --silent-install
hoptodesk --connect 123456789
hoptodesk --qs
hoptodesk --mcp

Log Files

If you're experiencing issues, log files can help diagnose the problem. You can share these with support when submitting a ticket.

Log File Locations

How to Access Logs on Windows

1. Press Win + R to open the Run dialog.
2. Type %APPDATA%\HopToDesk\log and press Enter.
3. The log folder will open in File Explorer.

How to Access Logs on macOS

1. Open Finder.
2. Press Cmd + Shift + G (Go to Folder).
3. Type ~/Library/Logs/HopToDesk and press Enter.

Firewall & Ports

You may need to make exceptions in your firewall settings to allow the following ports and protocols for HopToDesk to successfully make and receive connections:

Ports Used

Domains to Allow

For devices outside the LAN, you may also need to allow the following domains in your firewall:

• api.hoptodesk.com
• signal.hoptodesk.com
• signal2.hoptodesk.com
• turn.hoptodesk.com

Connection Issues

Common problems and solutions:

Cannot Connect to Remote Computer

• Verify the Device ID is correct and the remote computer is online.
• Ensure the remote computer has HopToDesk running and shows a "Ready" status.
• Check that incoming connections are not disabled in the remote computer's settings.
• If you're on a restrictive network, ensure outbound TCP 80/443 and UDP 49152–65535 are allowed (see Firewall & Ports).
• Check your firewall settings.

Connection is Slow or Laggy

• Lower the image quality in Display Settings (try "Optimize Reaction Time").
• Switch to a faster codec (VP8 uses less CPU; H.264/H.265 use hardware acceleration).
• If on the same network, check that you're getting a direct connection rather than relay (shown in the toolbar).
• Close bandwidth-heavy applications on both computers.

Black Screen After Connecting

• The remote computer may have privacy mode enabled - click the eye icon to toggle it off.
• On Windows, try requesting elevation from the Actions menu if the remote desktop is at a UAC prompt.
• Try switching the display codec in Display Settings.

Keyboard or Mouse Not Working

• Check that Keyboard & Mouse permission is enabled on the remote computer.
• On macOS, ensure Accessibility and Input Monitoring permissions are granted. See macOS Permissions.
• On Linux, the app may need elevated privileges for input control.

macOS Permissions

macOS requires explicit user permission for HopToDesk to capture the screen and control input. You'll be prompted on first launch, but you can also configure them manually:

Required Permissions

How to Grant Permissions

1. Open System Settings (or System Preferences on older macOS).
2. Go to Privacy & Security.
3. Select the permission category (e.g., Screen Recording).
4. Click the lock icon to make changes (enter your Mac password).
5. Find HopToDesk in the list and enable the toggle.
6. You may need to restart HopToDesk after granting permissions.

Dashboard Integration

Link your HopToDesk device to the HopToDesk Dashboard at dashboard.hoptodesk.com for centralized management.

• Link your device: In Settings, enter your Dashboard invite code or login credentials.
• Benefits: Centralized device management, synced address book, team management, support ticket tracking, and more.
• Unlink: You can unlink your device from the Dashboard at any time in Settings.

See the Dashboard documentation for full details on team and device management features.

Support Tickets

Get help directly from within the HopToDesk application:

1. Open HopToDesk and make sure your device is linked to the Dashboard.
2. Click the Support / Ticket option.
3. Fill in the subject and description of your issue.
4. Attach any relevant screenshots or files (up to 5 MB).
5. Select a priority level (Low, High, or Urgent).
6. Submit the ticket. You'll receive responses directly in the app.