JetBrains Gateway to the Toolbox App migration guide

The Remote Development functionality is currently being migrated to the Toolbox App, and JetBrains Gateway will be deprecated. This migration process should be carried out in agreement with current plugin authors and JetBrains Gateway users, to ensure a smooth transition and seamless integrations.

The migration guide aims to collect general feedback to understand the needs and expectations of plugin developers, ensuring the quality of the delivered APIs and workflows.

General goals of migration

The Toolbox App is the designated entry point for using JetBrains tools and provides integration with other JetBrains products, including JetBrains IDE Services.

Moving the entry point of Remote Development into the Toolbox App (as opposed to the standalone Gateway application), will improve the general user experience and simplify workflows. Additionally, it also will improve a plugin author experience, with cleaner APIs, unified UI, and easier workflows for common use cases.

Notable changes for plugin authors

Clean, small-scope plugin API

The Toolbox App did not support plugins until now, and the first release of plugin support targets only Remote Development. This means that the API surface can be designed precisely for that goal, with clear semantics, documentation, and separation from the Toolbox App itself. We aim to have decent backward compatibility guarantees. There are currently no plans for other types of plugins or extensibility of other features in the Toolbox App.

Introduction of Toolbox Agent

The new Remote Development model introduces Toolbox Agent – a small binary that can be used to manage IDE installations from command-line and scripts, making pre-installation and pre-configuration of IDEs easier and more straightforward. This also applies to updating them and monitoring Remote Development hosts.

Additionally, the same binary will be used by the Toolbox App in so-called Agent mode to perform operations on the host, including managing IDEs and connecting to them. The use of this binary is required, as it allows offloading many tasks related to managing IDEs on the host to the Toolbox App.

Plugins could provide a connection to the agent, through which the Toolbox App would be able to discover and connect to host IDEs. Installation, updates, and other operations would be also possible, depending on the host configuration.

For SSH-based flows, the binary can be automatically deployed by the Toolbox App upon connection. However, this capability will be eventually restricted – the binary will have to be present on the host before the Toolbox App connects to it.

Unified, simplified UI

We aim to provide users with a clean unified UI across all environments they are working with. The remote environment UI resembles the local one, thus easing the learning curve. For plugin developers, it also means less work crafting the UI.

The initial plugin API will not expose any UI components directly. Instead, a set of viewmodels for basic controls will be provided, which can be assembled into custom pages for many purposes, such as settings for the plugin, or a specific environment. The styling of components will be provided by the Toolbox App.

The main page with the list of environments and IDEs/projects within them will also be provided by the Toolbox App. Some degree of flexibility will be provided there, to accommodate various relationships between environments, IDEs and projects.

Unified URL handling

JetBrains Gateway offered support for jetbrains-gateway:// protocol URLs, but there were issues with the possibility of multiple JetBrains Gateway installations on a given machine (including JetBrains Gateway functionality used from other IDEs), and the URL format was not well-defined. With the Toolbox App, there’s always a single application to handle requests, and we’re structuring URLs a bit more to be clearly addressed to specific plugins. There’s still freedom to customize plugin-specific parts of the URL.

In Toolbox, jetbrains:// protocol will be used with the new URL scheme, requiring some updates for web pages. Limited backward compatibility for jetbrains-gateway:// protocol URLs is under consideration.

Better built-in SSH support

We’re switching to using the SSH binary directly for SSH connections. This should provide seamless compatibility with most setups, including the ones not supported by JetBrains Gateway. Plugin authors will be able to reuse most SSH workflows, similar to JetBrains Gateway.

Additionally, we’re taking care to provide way cleaner APIs to allow for a greater degree of flexibility with using or not using system SSH configuration, and overriding parts of it for plugin-specific connections.

As the baseline, providing SSH connection details is all that’s necessary for a basic Remote Development setup. This expands further to working with any alternative way of executing shell commands on the host and forwarding IO streams. Naturally, this is optional, and plugins are free to use as much or as little of SSH support as they need for their workflows.

Host-side configuration

It’s possible to provide certain configuration items on the host to fine-tune capabilities of the Toolbox Agent.

This is the incomplete list of capabilities that are planned:

Disabling new tool installation and existing tool upgrades [ready to use]
Changing paths where tools are installed [ready to use]
Specifying a list of allowed and prohibited tools [ready to use]
Disabling opening or creating new projects [not implemented yet]
Configuring STUN/TURN server for improved connectivity [not implemented yet

The Toolbox App Agent can be configured using a file put in the following location on the host:

LocalAppData/JetBrains/Toolbox/environment.json

~/Library/Application Support/JetBrains/Toolbox/environment.json

~/.local/share/JetBrains/Toolbox/environment.json

This JSON file has the following structure, as described using Kotlin data classes:

            @Serializable
            data class EnvironmentDescriptorDto(
              val tools: Tools? = null,
              val allowPortForwarding: Boolean? = null,
            ) {
              @Serializable
              data class Tools(
                val allowInstallation: Boolean? = null,
                val allowUpdate: Boolean? = null,
                val allowUninstallation: Boolean? = null,
                val allowLogCollection: Boolean? = null,
                val location: Collection<ToolLocation>? = null,
                val allowed: Collection<ToolFilter>? = null,
                val disallowed: Collection<ToolFilter>? = null,
              )

            @Serializable
            data class ToolLocation(
                @Serializable(with = OkioPathSerializer::class)
                val path: Path,
                /** The number of nested directory levels to be scanned.
               * When levels == 0 (default), `path` is considered as an IDE directory.
               * When levels == 1, `path` indicates a directory containing
               * one or more IDE directories inside, and so on. */
               val levels: Int = 0,
             )

            @Serializable
            data class ToolFilter(
                val type: ApplicationType, // e.g. "CLion", "Fleet", etc.
                val builds: Collection<BuildNumber>? = null, // e.g.
            listOf("232.8660")
            )
            }
        

Most fields are optional; if any fields are missing in the JSON, the specified default values will be used instead.

Updates

Update on the current state of the Toolbox App Plugin API (November 2024)

Currently, we are in the middle of moving away from our early API, plugin loading, and classloading for the Toolbox App plugins towards a more reliable and future-proof approach.

Major changes:

Now we use Java 21 so a plugin can use its classes and features now. The sample plugin was updated accordingly.
Several libs were leaking to the plugin API and classpath. In case you used it, please note that classes from okio and okhttp are not provided anymore in API and soon will be removed from the classpath.
API interfaces are moved between packages and modules The structure became more logical and not flat anymore. Many interfaces were moved away from remote-dev (previously gateway) package to ui and core to allow more types of plugins in the future that are not tied to remote-dev related classes.
Most Deprecated APIs are removed All the updates are available here: https://github.com/vladertel/toolbox-remote-dev-sample.

Current plan:

The API will evolve with breaking changes based on our vision and your requests until the plugin API is released.

The following changes are planned:

Localization support for user-visible strings in the API
Move plugin entry point classes from ServiceLoader to extension.json
Allow plugins to reuse built-in icons

12 May 2025