Skip to main content

Deep links

Stacklok Desktop registers a custom protocol handler that lets the Enterprise Cloud UI trigger actions in the desktop app. When you click Install on a server in the Cloud UI, your browser opens Stacklok Desktop with the server pre-selected.

How it works​

  1. The Cloud UI constructs a deep link URL using the stacklok-enterprise-gui:// protocol.
  2. Your browser opens the URL, which the operating system routes to Stacklok Desktop.
  3. Stacklok Desktop parses the URL, navigates to the server detail page, and opens the install modal.

Supported actions​

ActionURL formatWhat it does
Open server detailstacklok-enterprise-gui://v1/open-registry-server-detail?serverName=<NAME>Opens the registry detail page for the named server
Install serverstacklok-enterprise-gui://v1/open-registry-server-install?serverName=<NAME>Opens the detail page and shows the install modal

The serverName parameter must contain only alphanumeric characters, hyphens, underscores, and periods.

Protocol coexistence​

The enterprise protocol stacklok-enterprise-gui:// is separate from the open source protocol toolhive-gui://. Both editions can be installed on the same machine without conflict. Deep links from the Enterprise Cloud UI always open Stacklok Desktop. The toolhive-gui:// protocol is registered by the open source ToolHive desktop app.

Troubleshooting​

If clicking Install in the Cloud UI does not open Stacklok Desktop:

  • Verify that Stacklok Desktop is installed and has been launched at least once (the first launch registers the protocol handler with the operating system).
  • On Linux, verify that the .desktop file or Flatpak registration includes the x-scheme-handler/stacklok-enterprise-gui MIME type.
  • On macOS, if both editions are installed, verify that Stacklok Desktop is the default handler for stacklok-enterprise-gui:// URLs in System Settings > Default Apps.

Next steps​