Repository files navigation

Connects your JetBrains IDE to Coder workspaces

To install this plugin using JetBrains Toolbox, follow the steps below.

1. InstallJetBrains Toolbox. Make sure it's the2.6.0.40632 release orabove.
2. Launch the Toolbox app and sign in with your JetBrains account (if needed).

You can quickly install the plugin using this JetBrains hyperlink:

👉 jetbrains://gateway/com.coder.toolbox

This will open JetBrains Toolbox and prompt you to install the Coder Toolbox plugin automatically.

Alternatively, you can pastejetbrains://gateway/com.coder.toolbox into a browser.

There are two ways Coder Toolbox plugin can be installed. The first option is to manually download the pluginartifact fromJetBrains Marketplaceor fromCoder's Github Release page.

The next step is to copy the zip content to one of the following locations, depending on your OS:

• Windows:%LocalAppData%/JetBrains/Toolbox/plugins/com.coder.toolbox
• macOS:~/Library/Caches/JetBrains/Toolbox/plugins/com.coder.toolbox
• Linux:~/.local/share/JetBrains/Toolbox/plugins/com.coder.toolbox

Alternatively, you can install it using theGradle tasks included in the project:

./gradlew cleanAll build copyPlugin

Make sure Toolbox is closed before running the command.

You can use specially crafted JetBrains Gateway URIs to automatically:

1. Open Toolbox

2. Install the Coder Toolbox plugin (if not already installed)

3. Connect to a specific Coder deployment using a URL and a token.

4. Select a running workspace

5. Install a specified JetBrains IDE on that Workspace

6. Open a project folder directly in the remote IDE

jetbrains://gateway/com.coder.toolbox?url=https%3A%2F%2Fdev.coder.com&token=zeoX4SbSpP-j2qGpajkdwxR9jBdcekXS2&workspace=bobiverse-bob&agent=dev&ide_product_code=GO&ide_build_number=241.23774.119&folder=%2Fhome%2Fcoder%2Fworkspace%2Fhello-world-rsjetbrains://gateway/com.coder.toolbox?url=https%3A%2F%2Fj5gj2r1so5nbi.pit-1.try.coder.app%2F&token=gqEirOoI1U-FfCQ6uj8iOLtybBIk99rr8&workspace=bobiverse-riker&agent=dev&ide_product_code=RR&ide_build_number=243.26053.17&folder=%2Fhome%2Fcoder%2Fworkspace%2Fhello-world-rs

jetbrains://gateway/com.coder.toolbox  ?url=http(s)://<your-coder-deployment>  &token=<auth-token>  &workspace=<workspace-name>  &agent_id=<agent--id>  &ide_product_code=<IDE-code>  &ide_build_number=<IDE-build>  &folder=<absolute-path-to-a-project-folder>

If only a single agent is available, specifying an agent ID is optional. However, if multiple agents exist,you must provide either the ID to target a specific one. Note that this version of the Coder Toolbox plugindoes not automatically start agents if they are offline, so please ensure the selected agent is running beforeproceeding.

Ifide_product_code andide_build_number is missing, Toolbox will only open and highlight the workspace environmentpage. Coder Toolbox will attempt to start the workspace if it’s not already running; however, for the most reliableexperience, it’s recommended to ensure the workspace is running prior to initiating the connection.

This section explains how to set up a local proxy (without authentication which is not yet supported) and verify thatthe plugin’s REST client works correctly when routed through it.

We’ll usemitmproxy for this — it can act as both an HTTP and SOCKS5 proxy with SSLinterception.

1. Follow themitmproxy Install Guide steps for your OS.
2. Start the proxy:

mitmweb --ssl-insecure --set stream_large_bodies="10m"

mitmproxy can do HTTP and SOCKS5 proxying. To configure one or the other:

1. Openhttp://127.0.0.1:8081 in browser;
2. Navigate toOptions -> Edit Options
3. Update theMode field toregular in order to activate HTTP/HTTPS or tosocks5
4. Proxy authentication can be enabled by updating theproxyauth tousername:password

1. Start Toolbox
2. From Toolbox hexagonal menu icon go toSettings -> Proxy
3. There are two options, to use system proxy settings or to manually configure the proxy details.
4. If we go manually, add127.0.0.1 to the host and port8080 for HTTP/HTTPS or1080 for SOCKS5.
5. Before authenticating to the Coder deployment we need to tell the plugin where can we find mitmproxycertificates. In Coder's Settings page, set theTLS CA path to~/.mitmproxy/mitmproxy-ca-cert.pem

Enabling debug logging is essential for diagnosing issues with the Toolbox plugin, especially when SSHconnections to the remote environment fail — it provides detailed output that includes SSH negotiationand command execution, which is not visible at the default log level.

If you encounter a problem with Coder's JetBrains Toolbox plugin, follow the steps below to gather moreinformation and help us diagnose and resolve it quickly.

To help with troubleshooting or to gain more insight into the behavior of the plugin and the SSH connection tothe workspace, you can increase the log level toDEBUG.

Steps to enable debug logging:

1. Open Toolbox

2. Navigate to the Toolbox App Menu (hexagonal menu icon) > Settings > Advanced.

3. In the screen that appears, selectDEBUG for theLog level: section.

4. Hit the back button at the top.

There is no need to restart Toolbox, as it will begin logging at theDEBUG level right away.

⚠️Attention: Toolbox does not persist log level configuration between restarts.

Once enabled, debug logs will be written to the Toolbox log files. You can access logs directlyvia Toolbox App Menu > About > Show log files.

Alternatively, you can generate a ZIP file using the Workspace action menu, available either on the mainWorkspaces page in Coder or within the individual workspace view, under the option labeledCollect logs.

The Coder Settings allows users to control CLI download behavior, SSH configuration, TLS parameters, and datastorage paths. The options can be configured from the plugin's main Workspaces page > deployment action menu > Settings.

Binary source specifies the source URL or relative path from which the Coder CLI should be downloaded.If a relative path is provided, it is resolved against the deployment domain.

Enable downloads allows automatic downloading of the CLI if the current version is missing or outdated.

Binary directory specifies the directory where CLI binaries are stored. If omitted, it defaults to the data directory.

Enable binary directory fallback if enabled, falls back to the data directory when the specified binarydirectory is not writable.

Data directory directory where plugin-specific data such as session tokens and binaries are stored if notoverridden by the binary directory setting.

Header command command that outputs additional HTTP headers. Each line of output must be in the format key=value.The environment variable CODER_URL will be available to the command process.

The following options control the secure communication behavior of the plugin with Coder deployment and its available API.

TLS cert path path to a client certificate file for TLS authentication with Coder deployment.The certificate should be in X.509 PEM format.

TLS key path path to the private key corresponding to the TLS certificate from above.The certificate should be in X.509 PEM format.

TLS CA path the path of a file containing certificates for an alternate certificate authority used to verify TLScerts returned by the Coder deployment. The file should be in X.509 PEM format. This option can also be used to verifyproxy certificates.

TLS alternate hostname overrides the hostname used in TLS verification. This is useful when the hostnameused to connect to the Coder deployment does not match the hostname in the TLS certificate.

The following options control the SSH behavior of the Coder CLI.

Disable autostart adds the --disable-autostart flag to the SSH proxy command, preventing the CLI from keepingworkspaces constantly active.

Enable SSH wildcard config enables or disables wildcard entries in the SSH configuration, which allow genericrules for matching multiple workspaces.

SSH proxy log directory directory where SSH proxy logs are written. Useful for debugging SSH connection issues.

SSH network metrics directory directory where network information used by the SSH proxy is stored.

Extra SSH options additional options appended to the SSH configuration. Can be used to customize the behavior of SSH connections.

Changes made in the settings page are saved by clicking the Save button. Some changes, like toggling SSH wildcard support,may trigger regeneration of SSH configurations.

⚠️Attention: Token authentication is required when TLS certificates are not configured.

1. Check that the changelog lists all the important changes.
2. Update the gradle.properties version.
3. Publish the resulting draft release after validating it.
4. Merge the resulting changelog PR.