Documentation

Quick Connect

Enter a Device ID directly to connect without adding to your device list. Useful for one-time support sessions. Choose Connect (opens the desktop app), Web (opens the connection in your browser, no install needed), or Files (file transfer via the desktop app).

Connecting to a Device

Each device row has up to four actions on the right:

• Connect — opens a remote-desktop session in your installed HopToDesk app. Only shown for online devices.
• Web Connect (globe icon) — opens the connection in your browser via web.hoptodesk.com. No app install needed; works on Chrome OS, mobile browsers, or any machine where you can't install software.
• File Transfer (file icon) — opens a file-transfer session in the desktop app (desktop only).
• Wake — replaces Connect for offline devices that have a known MAC address. Sends a Wake-on-LAN packet via another online device on the same local network.
• ⋯ (kebab) — Notes, Delete device.

Mobile Layout

On phones, the device list renders as a stack of tap-to-connect cards instead of a table — tap anywhere on a card to start a Web Connect session. The desktop-app and File Transfer entry points are hidden on mobile (they require the HopToDesk desktop app, which doesn't run on iOS/Android).

Device Management

• Search & Filter: Find devices by name, filter by online/offline status, or sort by various criteria
• Bulk Actions: Select multiple devices (desktop only) to delete or move to groups at once
• Export: Download your device list as a CSV file for reporting
• Groups: Assign each device to a group from the inline + Add group button on the row

Device Details (Click device name to expand)

• Device Name: Set a friendly name for easy identification
• Notification Email: Get email alerts for this specific device
• Online/Offline Sound: Toggle audio notifications when device status changes
• Connection Info: View IP address, first connected date, last seen, and session count
• Session Log: Review recent connection history and export logs

Creating a Contact

1. Click Contacts in the sidebar
2. Click the Add Contact button
3. Fill in customer details:
   • Name (required) - Customer's full name
   • Email - For notifications and correspondence
   • Phone - Contact number
   • Company - Their organization
   • Notes - Any relevant information
4. Click Save Contact

Linking Devices to Contacts

Associate devices with their owners for better organization:

• From Contact: Open a contact and click Link Device
• From Device: Open device details and click Link Contact
• One contact can have multiple devices (e.g., laptop + desktop)

Managing Contacts

• Search: Find contacts by name, email, or company
• View History: See all tickets and sessions for a contact
• Create Ticket: Open a contact and click Create Ticket to start a support request linked to that customer
• Import/Export: Bulk import from CSV or export for backup

Creating an Invite

1. Open the Devices screen
2. Click + Create Invite in the top-right of the page header
3. An invite link and code are generated immediately — no form to fill
4. Copy the URL (or the short invite code) and share with your client

Need to find a previously-created invite? Click Pending Invites in the same header to browse, copy, or delete any open invite.

Reusable, Multi-Device by Default

Each invite link is reusable — one link can install HopToDesk on any number of devices. Each device that uses the link registers as a separate entry in your dashboard, automatically associated with the invite. This is ideal for rolling out a new fleet, sharing with a customer site, or letting an MSP team self-onboard.

SSO Invite Codes

If your account has SSO configured (see the SSO docs), you can also create SSO invite codes for org-wide auto-enrollment — the device installs the client, completes SSO sign-in once, and lands in your dashboard scoped to the right tenant. Useful for large deployments where you don't want to send a one-off URL to each user.

Sharing with Clients

Send the invite link to your client via:

• Email — copy and paste the link
• Chat / messaging — works in Slack, Teams, anywhere
• SMS — works on mobile too
• Short invite code — for users who'd rather type a 12-character code than a URL

What Happens When the Client Clicks

1. Client sees your branded install page (configured under Custom Branding → Invite Page)
2. The right HopToDesk client downloads automatically — your generated/branded version if you've set one up under Custom Branding → Custom Client Generator, otherwise the default
3. Once installed, the device registers and appears in your Devices list with real-time status
4. You can connect (Connect, Web Connect, or File Transfer) as soon as the device is online

1. Customer Creates via Support Portal

When customers run your invite link, a Support Ticket Portal is installed on their device:

• Customer right-clicks the support icon in their system tray
• Selects Create Support Ticket
• Fills in subject, description, and priority
• Ticket appears in your dashboard automatically linked to their device

2. You Create Manually in Dashboard

Create tickets on behalf of customers or for internal tracking:

1. Click Tickets in the sidebar
2. Click Create Ticket button
3. Fill in subject, description, priority, and optionally link a contact or device
4. Click Create

Shortcut: You can also create tickets directly from a Device or Contact by clicking Create Ticket in their details view.

3. Customer Creates via Website Widget

Embed a support widget on your website (see Support Widget section):

• Customer clicks the floating support button on your website
• Fills in their email, subject, description, and priority
• Ticket appears in your dashboard with their email for follow-up

Managing Tickets

• Status: Open, In Progress, Waiting, Resolved, Closed
• Priority: Low, Medium, High, Urgent
• Replies: Respond to client messages (they see it in their portal)
• Internal Notes: Add private notes only your team can see
• Link Device: Connect to a device for quick remote access
• Link Contact: Associate with a customer contact
• Assign: Transfer tickets to team members

Creating Groups

1. In the sidebar, click Devices to expand its dropdown — your existing groups are listed underneath
2. Click + Add Group at the bottom of the dropdown
3. Enter a group name and click Create

You can also assign individual devices to groups inline from the device row's + Add group link, or use bulk actions to assign many at once.

Use Cases

• By Client: "Acme Corp", "Smith Family"
• By Location: "Office", "Remote Workers"
• By Type: "Servers", "Workstations", "Laptops"

How Trash Works

• Deleted devices are moved to Trash and kept for 30 days
• After 30 days, trashed devices are automatically cleaned up
• The Trash icon in the sidebar shows the count of items currently in Trash

Managing Trash

• View Trash: Click Trash in the sidebar to see all deleted devices
• Restore: Click the restore button on a trashed device to move it back to your device list
• Empty Trash: Click Empty Trash to permanently delete all items at once

Widget Customization

• Brand Color: Match your website's color scheme
• Position: Bottom right or bottom left corner
• Greeting: Custom welcome message
• Company Name: Displayed in the widget header

Installation

1. Configure your widget settings in Widget Creator
2. Copy the generated code
3. Paste before the closing </body> tag on your website

1. Custom Client Generator

Build a fully white-labeled HopToDesk client (or paste your own self-hosted client URLs). Your app name, icons, company URLs, and branding images are baked into the binary at build time.

For a complete walkthrough — branding fields, plan tiers, build queue behavior, self-hosted URL setup, and troubleshooting — see the dedicated Custom Clients section below.

2. Invite Page

Brand the page clients land on when they open one of your invite links:

• Company Name and Logo — shown at the top of the install page
• Primary Color — color picker (hex), used for buttons and accents
• Live preview on the right shows changes as you edit

3. Email Notifications

Brand the transactional emails your account sends — ticket replies, invite reminders, account notifications. Logo, sender name, and color are picked up from the Invite Page tab; this tab lets you customise the email-specific parts.

Path 1: Generate a Custom Build

Plan tiers

• Trial — Windows builds only (.exe installer, code-signed)
• Pro / Enterprise — Windows, macOS (.dmg, unsigned — Gatekeeper warning), Linux (.deb, unsigned)

Step-by-step

1. Open Custom Branding in the sidebar → click the Custom Client Generator tab
2. Fill in the Branding column on the left:
   • App Name (required, max 40 characters, letters/numbers/spaces only) — appears as the installed app name and window title
   • App Icon (required, square PNG, 1024×1024 recommended) — all platform-specific icon files (.ico, .icns, etc.) are generated automatically in your browser, no separate uploads needed
   • Company Name, Company URL, Privacy Policy URL (all optional) — shown in the app's About / settings screens
   • Featured Image (optional, PNG, suggested 200×134) — replaces the default illustration on the Connect screen
   • Privacy Mode Image (optional, PNG exactly 1920×1080, ≤56,355 bytes — auto-padded to size) — shown on the remote screen when privacy mode is engaged during a session
3. Watch the Preview on the right update live as you type — this approximates what the real client window will look like (your icon top-left, your app name in the title bar, your featured image in the body)
4. Pick which OSes to build under Platforms — each one selected adds 5–20 minutes to the queue. Mac and Linux are greyed out on Trial accounts.
5. Decide whether to be emailed when the build is done (checkbox under the button), then click Generate Custom Build
6. Status appears in the panel below the form. The page also keeps a Your Custom Builds table further down with a row per build, status (queued, building, ready, failed), build time, and a Download link once ready

After the build

• Click Download on any ready build to grab the installer
• To use this build for invite links, scroll to Custom Client Download URLs below and click Use latest build for the matching OS — the field auto-fills with the right URL
• You can keep generating new builds whenever you change branding — old builds stay listed (and stay downloadable) until you delete them

Path 2: Host Your Own Client

If you compile the HopToDesk client yourself (forked source, custom build pipeline, internal CDN, etc.) and host the installers somewhere, paste your download URLs into the Custom Client Download URLs card at the bottom of the Custom Client Generator tab. Invite links will fetch from those URLs instead of the default HopToDesk client.

Per-OS URL examples

• Windows: https://yoursite.com/downloads/YourBrand.exe
• macOS: https://yoursite.com/downloads/YourBrand.dmg
• Linux: https://yoursite.com/downloads/YourBrand.AppImage

Leave any field blank and that OS will fall back to the default HopToDesk download. Mix and match freely — for example, generate Windows yourself and host Mac externally.

Requirements for self-hosted URLs

• Public HTTPS — the URL must be reachable without authentication (your customers' browsers fetch it directly)
• Stable filename — if you rotate filenames per release, point at a redirect/symlink that always serves the latest
• Correct content-type recommended (application/x-msdownload, application/x-apple-diskimage, etc.) — not strictly required but helps some browsers

How Invite Links Use Your Custom Client

Once a Custom Client Download URL is set for an OS, invite-link downloads work like this:

1. Customer opens your invite link on, say, Windows
2. Branded install page loads (configured under Custom Branding → Invite Page)
3. Customer clicks the download button — the file served is fetched from your custom_client_url_windows, with the filename rewritten to include the invite code (so the same binary can be reused across multiple invites without name collisions)
4. Customer runs the installer — sees your name, your icon, your URLs throughout
5. Once installed, the device registers in your dashboard automatically, scoped to the invite

No code or configuration on the customer side — the entire branded experience is delivered from your invite URL.

Updating or Replacing a Custom Client

• Generated builds: change branding fields and click Generate Custom Build again. When the new build appears in the table, click Use latest build in the Download URLs card — existing invite links pick up the new file immediately, no need to re-issue invites.
• Self-hosted: push your new installer to the same URL. Same effect — existing invites serve the new file the next time they're clicked.
• Already-installed clients keep running the version they were installed with — HopToDesk doesn't auto-update. To roll out a new branded version to existing devices, redistribute the new installer manually or have customers re-install from a fresh invite link.

Troubleshooting

• "Custom client URL appears unreachable" banner. The dashboard periodically health-checks each saved Download URL. If the URL stops responding (404, 5xx, DNS failure), this banner appears in the Custom Client Generator tab so you know the URL is broken before customers report it. Update the URL and the banner clears.
• Build stuck in "queued" or "building" for >30 minutes. Click Refresh on the Your Custom Builds table. If still stuck, generate a new build and let support know — the original build may have failed silently.
• Mac client says "unidentified developer" / Gatekeeper warning. Expected. Generated Mac builds are unsigned. Customers either right-click → Open the first time, or you can sign the .dmg yourself with your own Apple Developer ID before redistributing.
• Linux .deb fails to install. Make sure your customers are on a Debian/Ubuntu-based distro. The generator only produces .deb — for RPM-based or other distros, use the self-hosted URL path with your own packaging.
• App Name validation rejects characters. Letters, numbers, and spaces only, max 40 characters. No punctuation, slashes, or emoji — these would break filenames or installer registry keys on at least one platform.

Adding Team Members

1. Go to Settings
2. Find the Team Access section
3. Enter the team member's email
4. Click Invite

Team Collaboration

• Shared access to all devices
• Collaborate on support tickets
• View team member activity
• Add internal notes visible only to team

Toast Notifications

In-dashboard notifications appear in the bottom-right corner showing:

• Device online/offline status changes (shows device name)
• New support tickets
• Action confirmations

Sound Notifications

Enable per-device sound alerts:

1. Go to Devices
2. Click on a device name to expand details
3. Toggle Sound Alerts on

Sound is off by default to avoid noise with many devices. The toggle is per-device, so you can enable it only for the machines that matter.

Real-time Updates

The dashboard uses WebSocket connections for instant updates. Check the connection status indicator at the bottom of the sidebar.

Available Reports

• Activity Summary: Overview of device connections, session durations, and activity trends
• Device Status: Historical online/offline patterns for all devices
• Ticket Analytics: Response times, resolution rates, and ticket volume
• Team Performance: Team member activity and contribution metrics

Generating Reports

1. Go to Reports from the sidebar
2. Select the report type and date range
3. Click Generate Report
4. Export as CSV or PDF for sharing

Enabling Recording in HopToDesk

1. During a remote session, look for the video camera icon at the top of the connection window
2. Click the icon to start recording
3. Recordings are saved locally as WebM files on your machine
4. Click the icon again to stop recording

Using the Recording Library

1. Go to Recordings from the sidebar
2. Click Open Recording or drag and drop a WebM file
3. Use the video player to review the recording
4. Click Add Current to Library to catalog it
5. Add a title, notes, and optionally link to a device or ticket

Recording Library Features

• Catalog recordings with titles and notes
• Link recordings to specific devices for context
• Associate recordings with support tickets
• Search and filter your recording library

Setting Up 2FA

1. Go to Settings and find the Two-Factor Authentication section
2. Click Enable Two-Factor Authentication
3. Scan the QR code with your authenticator app (Google Authenticator, FreeOTP, Authy, etc.)
4. Enter the 6-digit code from your app to verify setup
5. Your account is now protected with 2FA

Compatible Authenticator Apps

• Google Authenticator - Available for iOS and Android
• FreeOTP - Open source option for iOS and Android
• Authy - Supports multi-device sync
• Microsoft Authenticator - Works with any TOTP-compatible service
• Any app that supports TOTP (RFC 6238)

Logging In with 2FA

1. Enter your email and password as usual
2. When prompted, open your authenticator app
3. Enter the current 6-digit code
4. You're logged in!

Disabling 2FA

To disable 2FA, you'll need both your password and a current 2FA code:

1. Go to Settings > Two-Factor Authentication
2. Click Disable Two-Factor Authentication
3. Enter your password and current 2FA code
4. 2FA will be disabled

What is SSO?

Single Sign-On lets employees use their existing corporate credentials (the same login they use for email, Slack, etc.) to access HopToDesk Dashboard. Benefits include:

• No password fatigue - Users don't need another password to remember
• Centralized access control - Disable access instantly when employees leave
• Automatic provisioning - New employees get access immediately
• Enterprise compliance - Meet security requirements for corporate tools

Note: SSO login is available on the Pro plan.

Supported Identity Providers

• Okta - Enterprise identity management
• Microsoft Azure AD (Entra ID) - Included with Microsoft 365 Business
• Google Workspace - Included with Google Workspace (paid plans)
• Other OIDC Providers - Any provider supporting OpenID Connect (Auth0, OneLogin, Keycloak, etc.)

Setting Up SSO (Admin)

1. Create an OIDC application in your IdP:
   • Application type: Web Application
   • Grant type: Authorization Code
   • Redirect URI: https://YOUR-DASHBOARD-URL/api?action=ssoCallback
2. Get your credentials from the IdP:
   • Client ID
   • Client Secret
   • Issuer URL (e.g., https://your-company.okta.com)
3. Configure in Dashboard Pro:
   • Go to Settings → scroll to Single Sign-On (SSO)
   • Select your provider type
   • Enter the Issuer URL, Client ID, and Client Secret
   • Enter allowed email domains (e.g., yourcompany.com)
   • Click Test Connection to verify
   • Click Save SSO Settings

Provider-Specific Setup Guides

How Users Log In with SSO

1. Go to the HopToDesk Dashboard login page
2. Enter your work email address
3. Click the SSO button (next to the Login button)
4. You'll be redirected to your company's login page
5. Sign in with your corporate credentials
6. You'll be automatically logged into the dashboard

SSO Options (Pro)

• Auto-provision users - Automatically create dashboard accounts for new SSO users on first login
• Default role - Set the role (Admin, Member, or Viewer) for auto-provisioned users
• Allowed domains - Restrict SSO to specific email domains

Deployment Management

Track and manage mass device rollouts across your organization. Deployments help you plan, execute, and monitor large-scale HopToDesk installations.

How to create a deployment:

1. Go to the Deployments tab and click New Deployment
2. Enter a descriptive name (e.g., "Q1 2026 - Engineering Floor 3")
3. Select the target device group where new devices will be assigned
4. Set the expected device count so you can track progress
5. Optionally associate an SSO invite code for automated enrollment

Deployment statuses:

• Active - Deployment is in progress; devices are still registering
• Paused - Temporarily halted; no new registrations accepted
• Completed - All target devices have been registered or the deployment was manually marked complete

Use case: You're rolling out HopToDesk to 500 machines in a new office. Create a deployment, share the invite link with the IT team on-site, and monitor registration count from your dashboard.

Conditional Access Policies

Access policies define rules that are evaluated before every connection attempt. If a connection does not meet all active policy conditions, it is blocked.

Policy types:

• IP Whitelist - Only allow connections from specific IP addresses or CIDR ranges (e.g., 192.168.1.0/24). Use for office-only access.
• Time-Based - Restrict connections to specific hours (e.g., Mon-Fri 8am-6pm). Prevents after-hours unauthorized access.
• Feature Restriction - Disable specific session features (file transfer, clipboard, USB) for certain groups. Useful for compliance.
• Device Group - Apply a policy only to devices within a specific group. Lets you have different rules for servers vs. workstations.
• Approval Required - Require a manager or admin to approve each connection request before it proceeds. Best for sensitive production systems.
• Geo-Fence - Restrict access by geographic region. Block connections originating from countries where your organization does not operate.

Tip: Policies can be combined for defense-in-depth. For example, combine IP whitelist + time-based + approval required for maximum security on critical infrastructure.

Roles & Permissions (RBAC)

Control exactly what each team member can see and do with fine-grained, role-based access control.

Built-in roles:

• Owner - Full access to everything, including billing and enterprise settings. Cannot be deleted.
• Admin - Full access except billing. Can manage team members, devices, and all features.
• Member - Can view and connect to devices, manage tickets, but cannot change settings or manage team.
• Viewer - Read-only access. Can view devices and tickets but cannot connect or make changes.

Available permissions (12 total):

Use case: Create a "Helpdesk L1" role with only Device View, Device Connect, and Ticket View/Manage permissions. Junior technicians can handle tickets and connect to devices without accessing settings or reports.

Directory Sync (AD/LDAP)

Automatically provision and deprovision dashboard users by syncing with your identity provider. When employees join or leave your organization, their dashboard access is updated automatically.

Supported providers:

• Active Directory - On-premises AD via LDAP protocol
• LDAP - Generic LDAP-compatible directories
• Azure AD (Entra ID) - Microsoft's cloud identity service
• Okta SCIM - Okta-based provisioning via SCIM protocol

Configuration fields:

• Server URL - Your LDAP server address (e.g., ldap://dc.company.com:389 or ldaps://dc.company.com:636 for SSL)
• Base DN - The root of your directory tree to search (e.g., DC=company,DC=com)
• Bind DN - The service account used to authenticate with the directory (e.g., CN=ServiceAccount,OU=Users,DC=company,DC=com)
• Bind Password - Password for the service account
• Sync Interval - How often to sync: every hour, every 6 hours, every 24 hours, or manual only

Tip: Use "Test Connection" to verify your settings before enabling automatic sync. The Sync Status panel shows the last sync time and counts of added/updated/removed users.

Device Policies

Enforce session-level security rules on a per-group basis. Device policies control what features are available during remote sessions for devices in a specific group.

Configurable controls:

• File Transfer - Allow or block file transfers during sessions
• Clipboard Sharing - Allow or block copy/paste between local and remote machines
• Session Recording - Force-enable or disable session recordings
• 2FA Requirement - Require two-factor authentication for connections to devices in this group
• Session Timeout - Automatically disconnect sessions after a specified idle time

Use case: Create a "Production Servers" policy with file transfer disabled, recording enabled, and 2FA required. Apply it to your production device group. A separate "Development" policy can be more permissive.

Compliance Readiness Tracker

Self-assess your organization's readiness against major regulatory and industry compliance frameworks. Each framework is broken down into individual controls that can be marked as compliant, partially compliant, or non-compliant. This tool helps you prepare for formal audits by tracking your compliance posture internally.

Note: This is a readiness tracking tool for internal self-assessment. Formal compliance certifications (SOC 2 Type I/II reports, HIPAA attestations, ISO 27001 certificates, PCI DSS ROCs/SAQs) require engagement with a qualified third-party auditor or assessor.

Supported frameworks:

• SOC 2 - Trust Service Criteria for security, availability, processing integrity, confidentiality, and privacy (37 controls)
• ISO 27001:2022 - International standard for information security management systems (93 Annex A controls)
• HIPAA - Health Insurance Portability and Accountability Act security rule safeguards (48 controls)
• GDPR - General Data Protection Regulation for EU personal data protection (36 articles)
• PCI DSS v4.0 - Payment Card Industry Data Security Standard (64 requirements)
• NIST CSF - NIST Cybersecurity Framework: Identify, Protect, Detect, Respond, Recover (98 subcategories)

How to use:

1. Select a framework from the dropdown filter
2. Click "Update" on each control to set its status and document evidence
3. Record notes about evidence, documentation links, or gaps that need attention
4. Use "Export CSV" to generate a readiness assessment for your compliance team or auditor preparation

The readiness score cards at the top provide a quick overview of your self-assessed compliance posture across all frameworks. Scores are calculated as: (compliant controls + 50% of partial controls) / total applicable controls.

SLA Management

Define service level agreements that set response and resolution time targets for support tickets. The system automatically tracks whether your team meets these targets based on ticket activity.

How SLAs work:

• Response Target - Maximum time before a team member first responds to a ticket (e.g., 15 min for Critical)
• Resolution Target - Maximum time to fully resolve the ticket (e.g., 4 hours for Critical)
• Priority Levels - Define different targets for Critical, High, Medium, and Low priority tickets

Dashboard metrics:

• SLAs Met - Number of tickets resolved within the target timeframe
• SLAs Breached - Number of tickets that exceeded the target
• Compliance Rate - Percentage of tickets meeting SLA targets over the last 30 days

Use case: Set a 15-minute response target and 4-hour resolution target for Critical tickets. If compliance rate drops below 90%, investigate staffing during peak hours.

Customer Satisfaction (CSAT) Surveys

Measure how satisfied customers are with your support by automatically sending feedback surveys after tickets are resolved.

Setup:

1. Toggle the survey switch to ON in the Survey Settings section
2. Customize the Survey Prompt (the question customers see, e.g., "How would you rate your support experience?")
3. Customize the Thank You Message shown after they submit their rating
4. Click Save Settings

Understanding the metrics:

• Avg Score (1-5) - Mean satisfaction rating across all responses. 4.0+ is generally considered good.
• Total Responses - Number of customers who completed the survey
• Response Rate - Percentage of resolved tickets where the customer submitted feedback
• NPS Score (-100 to +100) - Net Promoter Score calculated from ratings. Scores above 0 are positive; above 50 is excellent.

ITSM Integrations

Connect your dashboard to external IT Service Management tools for bi-directional data sync. Tickets, incidents, and notifications flow between systems automatically.

Available integrations:

• ServiceNow - Sync tickets and incidents with your ServiceNow instance. Requires an API key from your ServiceNow admin.
• Jira Service Management - Create and track Jira issues from dashboard tickets. Uses Jira API tokens for authentication.
• Zendesk - Link dashboard tickets to Zendesk support tickets. Bi-directional status updates.
• Freshdesk - Bi-directional ticket sync with Freshdesk helpdesk. Keeps both systems in sync.
• Slack - Send real-time alerts (new tickets, SLA breaches, device events) to Slack channels via incoming webhooks.
• Microsoft Teams - Post notifications and alerts to Teams channels. Uses Teams webhook connectors.

How to connect:

1. Click Configure on the integration card
2. Enter your API key, token, or webhook URL from the external service
3. Save the configuration - the status will change to "Connected"
4. Data sync begins automatically based on the integration type

Multitenancy

Manage multiple isolated organizations (tenants) under a single parent console. Each tenant has its own devices, users, settings, and data that is completely separate from other tenants.

Creating a tenant:

1. Click New Tenant and enter the organization name
2. Assign a tenant admin (email address) who will manage that tenant
3. The tenant admin receives an invitation and can begin adding devices and users

What gets isolated per tenant:

• Devices and device groups
• Team members and roles
• Tickets and session history
• Settings and branding
• All enterprise features (policies, SLAs, compliance data, etc.)

Ideal for: MSPs managing multiple client organizations, enterprises with regional offices or subsidiaries, and holding companies needing separate environments per business unit.

API Keys

Generate API keys for programmatic access to your dashboard data via the REST API. Use API keys for automation, custom reporting, or integrating with your own internal tools.

How to use:

1. Click Generate API Key and enter a descriptive name
2. Select permission scopes to control which data the key can access
3. Copy the generated key immediately - it is only shown once
4. Store the key as an environment variable: export HOPTODESK_API_KEY=hdpk_...
5. Use the key as a Bearer token: Authorization: Bearer hdpk_...

Example request:

Available endpoints by scope:

API keys provide read-only access. Each key can only access endpoints matching its assigned scopes.

• devices - getDevices, getDeviceStatuses, getDeviceDetails, getGroups
• tickets - getTickets, getTicketStats
• sessions - getActivityLogs, getUnattendedLogs, getFileTransferLogs
• contacts - getContacts, searchContacts
• invites - getInvites
• reports - getReportStats, getUsageAnalytics, getSecurityReport

Key management:

• Track usage with the Requests (30d) counter per key
• Last Used shows the most recent API call for each key
• Revoke compromised keys immediately - revocation takes effect instantly
• Create separate keys for different integrations or environments

Available Plans

• Trial: Free, no credit card required. 3 devices, ticketing & CRM, basic reports.
• Pro ($15/mo): 120 devices, up to 3 team members, branding, SSO login, full reports.
• Enterprise ($49/mo): 700 devices, unlimited team members, deployments, device policies, SSO Connect & SCIM, advanced reports, and all Enterprise features.

Usage Tracking

The Billing page shows your current usage for:

• Devices: How many devices you've added vs. your plan limit
• Team Members: Active team members vs. your plan limit

Device Packs (Enterprise)

Enterprise customers can purchase additional device packs of 700 devices each for $49/month per pack. This lets you scale beyond the base 700 device limit without switching plans.

Managing Your Subscription

• Upgrade: Click the upgrade button on a higher plan to switch immediately
• Cancel: Cancel your subscription from the Billing page. You'll retain access until the end of your billing period.
• Resume: If you cancelled, you can resume your subscription before it expires
• Payment Method: Update your card or view your payment portal via the links on the Billing page
• Billing History: View past charges and payment events at the bottom of the page

What is MCP?

The Model Context Protocol (MCP) is a standard for AI agents to interact with external tools. HopToDesk implements an MCP server that exposes desktop control tools over WebSocket. Your AI agent sends JSON-RPC 2.0 requests, and HopToDesk executes them on the target device.

Two connection modes are supported:

• Local: Agent and HopToDesk on the same machine — direct localhost WebSocket
• Remote: Agent connects through the dashboard relay to reach any enrolled device

Available MCP Tools

When connected, AI agents can use these tools:

Setup: Local Agent (Same Machine)

Use this when the AI agent runs on the same computer as HopToDesk. No dashboard enrollment or API key needed.

1. Download and install HopToDesk from hoptodesk.com
2. Run HopToDesk — the MCP server starts automatically and listens on ws://127.0.0.1:9333
3. Add to your AI agent's MCP config (example for Claude Code):

   {
     "mcpServers": {
       "hoptodesk": {
         "url": "ws://127.0.0.1:9333"
       }
     }
   }

4. Verify the connection — ask your AI agent to take a screenshot or list windows

Setup: Remote Agent (Via Dashboard)

Use this when the AI agent needs to reach a device on a different machine. Commands are relayed securely through the HopToDesk dashboard.

1. Install HopToDesk on the target device and enroll it using an invite link from the Devices screen
2. Create an MCP API key from AI Agent → Getting Started → Advanced
3. Find the device_id in Devices and copy it
4. Add to your AI agent's MCP config:

   {
     "mcpServers": {
       "hoptodesk-remote": {
         "url": "wss://dashboard.hoptodesk.com/ws/mcp?api_key=YOUR_API_KEY"
       }
     }
   }

5. Target a device — include device_id in your MCP tool calls to specify which device receives the command

Security

• Local connections are restricted to 127.0.0.1 only — no external access
• Remote connections require a valid API key with the mcp scope
• API keys can be revoked at any time from the Agents → API Keys tab
• All remote traffic is encrypted over WSS (TLS) through Cloudflare's network
• Agent sessions are isolated — one API key cannot access another user's devices
• MCP does not affect human users — human remote support sessions use a completely separate connection path (signal + TURN servers)

Troubleshooting

• Cannot connect locally: Make sure HopToDesk is running. The MCP server starts automatically on port 9333. Check that nothing else is using that port.
• Cannot connect remotely: Verify the API key has the mcp scope and has not expired or been revoked. Ensure the target device is online (green dot in the Devices tab).
• Commands not reaching device: The device must be enrolled in your dashboard account and showing as online. Check the device_id is correct.
• Screenshot returns empty: On some headless Linux servers, a display server (X11/Wayland) must be running for screenshots to work.

1. Device Tags

Tags are flat labels you attach to devices. A device can have many tags. Use them to group devices by role, location, OS, customer, or any dimension that matters for operations.

Setup

1. Open Devices and select a device.
2. In the Tags field, type a tag name and press Enter. Tag names are normalized to lowercase, with only a–z, 0–9, -, _, and : allowed (max 64 chars).
3. Repeat for each device. A device can hold up to 32 tags.

Naming conventions that work well

• By role: web, db, workstation, kiosk
• By environment: prod, staging, dev
• By location: office-nyc, office-london, home
• By OS: win, mac, linux
• By customer: client:acme, client:contoso

Tip: a device can belong to all of these at once. A server might be tagged linux, prod, web, office-nyc, client:acme — then any of those tags can target it.

2. Auto-Approve Rules

By default, destructive commands (reboot, kill process, clear temp files) need human approval before they run. Auto-approve rules let owners pre-authorize specific commands for specific people on specific devices — so routine work doesn't stall in the queue.

How a rule matches

A rule has three filters. All three are ANDed together. An empty filter means "match anything."

• Role — owner, admin, member, viewer, or blank for any role
• Operation — exact name (restart_hoptodesk), category glob (diagnostics:*), or * for any op
• Tag — the device must have this tag (blank matches any device)

Rules are evaluated in priority order (lowest number first). The first match wins and its action (approve or deny) is applied. If nothing matches, the default approval flow runs.

Setup

1. Open Agents → Auto-Approve Rules (owner only).
2. Click New Rule. Give it a descriptive name like "Admins auto-approve diagnostics on servers".
3. Pick role (or leave blank), operation pattern, and tag. Set action to approve or deny.
4. Set priority: 10–50 for deny rules that must win, 100+ for allow rules. Lower fires first.
5. Enable the rule and save. It applies to all new commands immediately.

Recommended baseline

Priority 10 — DENY "reboot_device" on tag "prod"  (any role)
Priority 20 — DENY "kill_process" on tag "prod"    (role=member)
Priority 100 — APPROVE "diagnostics:*" on any tag (role=owner)
Priority 110 — APPROVE "diagnostics:*" on any tag (role=admin)
Priority 120 — APPROVE "diagnostics:*" on tag "lab" (role=member)

This gives owners/admins frictionless diagnostics everywhere, lets the help desk run diagnostics on lab machines, and hard-blocks accidental reboots of production boxes.

3. Fan-Out: One Command, Many Devices

Fan-out takes an operation and a target (tags, device list, or everything) and runs it on every matched device in parallel. You get back a single job_id with aggregated progress, plus a per-device breakdown so you can see exactly what happened where.

Target kinds

• tags — union of all devices that have ANY of the listed tags
• devices — explicit list of device IDs
• all — every exec-enabled device on the account

Only devices that are exec-enabled and not deleted are included. Soft limit is 1,000 devices per fan-out — narrow the target if you hit it.

How it flows

1. You submit the fan-out. The backend resolves the target to a device list.
2. For each device: check auto-approve rules, create a remote_exec_log row, dispatch via the device's MCP channel.
3. Auto-approved commands start immediately; commands that need approval land in the approval queue and stay paused until an admin clicks Approve.
4. As each device responds, the per-device row is marked completed or failed, and the job's aggregate counters update.
5. When all devices finish (or time out after 5 min), the job is marked completed / partial / failed and you get a fanout:completed event.

Tracking a job

• Real-time progress arrives over your open dashboard WebSocket as fanout:progress events.
• Final status (completed / partial / failed / cancelled) fires once as fanout:completed.
• Full history is in Agents → Fan-Out History — click any job to see the per-device status table.

Cancel a running job

Admins can cancel any in-flight fan-out. Pending commands in the approval queue are rejected immediately; commands already running on a device finish naturally (you can't un-send a command that's mid-flight).

4. Scheduled Runbooks

A runbook is a saved fan-out that re-runs on a schedule. Perfect for nightly hygiene, weekly patches, or hourly health checks. The scheduler ticks every 5 minutes server-side and dispatches any runbook whose next-run time has passed.

Setup

1. Open Agents → Runbooks → New Runbook.
2. Pick the operation (e.g. disk_usage, clear_temp_files, run_update_check).
3. Pick the target: tags (recommended), explicit device list, or all.
4. Pick the cadence:
   • Sub-daily — interval in minutes (min 5). Runs every N minutes from creation.
   • Daily or multi-day — set interval to 1440 (daily), 4320 (every 3 days), etc., plus anchor hour/minute in UTC. Runs at the specified wall-clock time.
5. Save. The first run is scheduled based on the cadence; subsequent runs roll forward automatically.

Runbook behavior

• Runbooks bypass approval — the act of saving an enabled runbook is the approval. Use them for trusted, pre-vetted operations only.
• Each run creates a normal fan-out job tagged with source scheduler:<runbook_id>, so results sit alongside manual fan-outs in history.
• Disable a runbook any time by toggling Enabled off. The row stays; its schedule just pauses.
• Use Run Now to trigger an ad-hoc run without waiting for the next tick — handy for testing.

End-to-End Setup Example

Here's the full path from a freshly-enrolled account to a nightly cleanup job running across 50 workstations:

1. Enable Agents. Go to the AI Agent tab, accept terms, click Enable Agents. One click turns on fan-out, runbooks, and AI chat; every existing device is opted in automatically. Default rate limit is 30 commands/hour.
2. Tag the devices. Bulk-tag your 50 workstations with workstation and your office tag (e.g. office-hq).
3. Write an auto-approve rule. Owner auto-approve maintenance:* on tag workstation, priority 100. This lets the runbook proceed unattended.
4. Create the runbook. Operation clear_temp_files, target tag workstation, interval 1440, hour 3 (3am UTC).
5. Verify. Click Run Now. Watch the progress stream. Drill into the job in history to confirm every device completed.
6. Leave it running. Tomorrow at 03:00 UTC the cron ticks, the runbook fires, 50 devices clean up temp files in parallel. You get a single job row in history to scan each morning.

Use Cases

Troubleshooting

• "Remote execution is not enabled for this account." — Click Enable Agents on the AI Agent tab. Owner only.
• "Remote execution is not enabled on this device." — The device registered before you enabled Agents. Click Disable then Enable Agents again to opt every device back in.
• "No exec-enabled devices matched the target." — Either the tag has no devices, or none of the matched devices are exec-enabled. Check Devices filtered by that tag.
• Command stuck in "running" for more than 5 min — The device didn't respond. The watchdog flips it to timeout automatically on the next 5-min cron tick.
• Fan-out job hangs at partial progress — Same cause as above: some devices dropped off. Watchdog will close the job as partial or failed.
• Auto-approve rule isn't firing — Check priority ordering (lowest fires first) and that the rule is enabled. A deny rule at a lower priority will shadow a later approve.
• Rate limit exceeded — Default is 30 commands/hour/account.
• Need to revoke everything immediately — Click Disable on the AI Agent tab. All in-flight and pending commands are blocked.